Secure Backend APIs and Web Services

Create an API resource

To secure your backend APIs and web services, first you must create a resource in your tenant. For registration you can provide an API endpoint or an API identifier. API Endpoint can be your resource server's canonical URL or API gateway URL. Alternatively, you can use a unique identifier for you API resource.

Create resource permissions

Create required resource permissions. Create a new role, and attach one or more resource permissions to the role. Next assign role to the users.

Workflow

  1. After user authorization, the Client application will obtain tokens (id token and access token) from authorization server.
  2. Next, the client should make API requests to the resource server with the bearer access token as the authorization header in every API request.
  3. Resource server will first validated the token according to steps described below,
    1. Resource server backend will get the public portion of the keys used for signing access tokens from tenant's JWKS endpoint
    2. As best practice the resource server can cache response from JWKS endpoint, i.e. list of public keys for a short period (15-30 minutes).
    3. Next, the resource server will validate the access token signature using the public key and the algorithm used to sign the access token payload. If the token is invalid, it will raise the HTTP 401 unauthorized error.
    4. Next, the resource server will validate if it is the intended recipient of the token, by checking if the aud claim includes API endpoint or identifier. If the resource server is not intended recipient, it will raise the HTTP 401 unauthorized error.
    5. Next, the resource server will validate scope, sub, roles and permissions claims embedded in the token to ensure that the token bearer has the correct level of access. If a token has insufficient rights to a resource or does not match with the requirements of specific API action, it will raise a HTTP 403 forbidden error.
    6. Finally, if all previous validations and checks are are successful the resource server should return a response with HTTP status code 200.
  4. If the resource server return a successful response (HTTP status code 200), then the Client should process the returned data and display the user.
  5. If the resource server raises an unauthorized error (HTTP status code 401), then the client should intercept the error and try to obtain a new token from the authorization server.
  6. If the resource server raises a forbidden error (HTTP status code 403), then the client should display the return error to the user.
sequenceDiagram; participant C as Client Application; participant R as Resource Server; participant J as JWKS Endpoint; C-->>R: API Request; Note right of C: Include bearer
access token as
authorization
header in every
API request; R-->>J: Get Public Keys; J-->>R: RSA and EC Keys; loop Validate Token; R->>R: Validate token signature using public
key and algorithm used to sign the token; R->>R: Check if token audience (aud) claim
includes API endpoint or identifier for API; R->>R: Validate scope, roles and permissions
embedded in the access token; end rect rgb(238, 244, 255); alt token is valid; R->>C: Successful Response, 200; else token is invalid; R->>C: Unauthorized Error, 401; else insufficient rights; R->>C: Forbidden Error, 403; end end