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.
- 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.
- A factors API is invoked by the API client, then the JWT is presented back to
- 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.
- The subsequent calls to factors are preformed by the API client whenever a token with the
- Policy auth is initiated.
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
.