Deploying an API client

An API client is deployed within the application server portion of a web-app. A user interaction starts actions that are taken by the API client.

User actions

The steps that a user takes on the web application are tied to the actions taken by the API client.
  1. The user logs in.
    • Policy auth is initiated.
      • If a deny is returned, the application returns an error page to the user that indicates that the user cannot currently log in.
      • The application can provide a varied UX based on the factor required.
      • Alternatively, this step is skipped and ROPC is performed after a user provides credentials. Password is the only first factor that can be performed.
    • The user provides authentication data.
      • A factors API is invoked by the API client, then the JWT is presented back to /token.
      • If no further authentication is required, the user is now authenticated. If MFA is required, a suitable UX is returned to the user.
    • The user completes MFA
      • The subsequent calls to factors are preformed by the API client whenever a token with the mfa_challenge scope is returned.

Sovereignty of the access token

When you deploy an API client that uses ISV APIs for authentication, you must decide what is done with the access token and possibly the refresh token that is issued as a result of this flow.

Details to consider.
  • Return only full access tokens to the browser. When an mfa_challenge is returned, the browser session enters a transaction.
  • Keep refresh token on the application server.
  • If the access token is returned to the browser, the web application includes logic for detect an expired access token. That is, a 401 or 403 condition from a protected API. That condition starts a refresh token flow on the application server and a new token is issued to the browser. This flow allows an additional mfa_challenge to be returned when MFA is required.

Resource server considerations

An additional check must be performed,
  • When you deploy a resource server that consumes access tokens that are issued to a client through access policy for API grant types.
  • when introspection is done on an access token that is issued by ISV.
An mfa_challenge access token returns
"active": true
upon introspection. The resource server must include a check that the scope of the access token that is introspected is not mfa_challenge.
An example introspection of an mfa_challenge token.
{
  "entitlements": [
    "authn",
    "readEnrollMFAMethod"
  ],
  "at_hash": "Z3vQf5X3vzGu7sYqJShe_g",
  "ext": {
    "tenantId": "securitypoc.ice.ibmcloud.com"
  },
  "sub": "6030003FNL",
  "amr": [
    "password"
  ],
  "uniqueSecurityName": "6030003FNL",
  "iss": "https://securitypoc.ice.ibmcloud.com/oidc/endpoint/default",
  "active": true,
  "token_type": "Bearer",
  "client_id": "89136d7c-564b-4ea4-aa5b-19b0d9a8a47f",
  "aud": "89136d7c-564b-4ea4-aa5b-19b0d9a8a47f",
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "restrictEntitlements": true,
  "scope": "mfa_challenge",
  "grant_id": "bdbdd509-2866-46cd-b5cf-f5c5a4385691",
  "category": "application",
  "exp": 1594019673,
  "app_id": "2512439131051198658",
  "iat": 1594017873
}
Note: For a mfa_challenge token that didn't do an MFA yet, the entitlement is authnAnyUser.