Here’s an interesting pattern that we’re constantly running into at various API Management projects: runtime mapping between a token used by external mobile applications and another form of authentication required by an internal system. The need for this comes up when a legacy API/service with an existing access control mechanism needs to be exposed to a mobile application for which the current access control mechanism is not appropriate.
Example 1: Kerberos-Constrained Delegation
Services and APIs developed using Microsoft stacks often expect a Windows identity at runtime for role-based authorization. Providing a Kerberos ticket all the way to a mobile device outside the security domain is an anti-pattern. Instead, the user of the mobile application is subjected to an OAuth handshake. The authorization server leverages the user credentials at handshake time to also get a Kerberos ticket on behalf of this user and stores it as part of the OAuth session – see the token lifecycle management concept explained in this previous post. The OAuth access token is mapped to the Kerberos ticket at runtime when the API calls are made by the mobile application.
Example 2: An SSO Token
Many backend services were originally intended to be consumed by Web applications. When the user of a Web application logs into the Web portal, a session is created in the IAM solution and when the Web portal needs to consume the internal API on behalf of the user, it leverages this same SSO token. I’m thinking here of solutions such as CA SiteMinder, Oracle Access Manager etc. When this same API is now consumed by a native mobile application, instead of a Web application, the existing login flow is no longer adequate. Again, an OAuth authorization server is leveraged to create a session between the mobile application and the API Management infrastructure. In this case, the OAuth authorization server will get the SSO token created at the same time as the front-side access token and map between the two at runtime.
This pattern is applicable no matter what the internal token is. Other common forms for these internal tokens include a SAML assertion issued by an STS and session IDs issued by the backend service itself through a /login method. Note that baking such login methods directly into an API constitutes an anti-pattern but the token mapping offers a non-intrusive “resolution”, which restores proper decoupling at the perimeter whilst avoiding any change to the legacy backend.
During an initial OAuth handshake, the OAuth authorization server is provided with credentials for the user. These credentials might be provided by the application itself in the case of a resource-owner-password-credentials grant type or by the user via a login form directly on the OAuth authorization server. The best practice is to use password grants for trusted applications (applications provided by the same provider of the API itself) and to use the implicit or authorization-code grant type for third-party applications. These credentials are used by the OAuth authorization server to authenticate the user and issue an access token. In addition to this, the OAuth authorization server may use the user credentials during this same process, to get an internal token issued by doing its own handshake with the internal token server/STS or by making a /login–style API call. The OAuth access token is returned to the mobile application and both tokens are stored as part of the OAuth session, alongside the other properties of the session, such as scope, timestamps etc. Note that there is often a temptation to store the user credentials as part of this session for later use but this is not recommended.
It makes sense to align the life spans of both the internal and external tokens so that they can be reissued together when they expire. Whenever these tokens need to be reissued, the OAuth authorization server will again be the component driving this. For better user experience, the mobile application will often want to avoid prompting the user for credentials. The OAuth standard accommodates this through the concept of refresh tokens but the internal token issuing pattern doesn’t always do that. For example, Kerberos-constrained delegation will let you get a new Kerberos token without the user’s password but other systems will not allow for that. This is often the source of motivation for storing the user credentials as part of the user session as mentioned above. You can instead allow for an internal token with a longer lifespan than the external token and reuse the existing internal token at OAuth refresh time.
At runtime, the mobile application consumes an API on behalf of the user by calling the OAuth resource server, the runtime analog of the OAuth authorization server.
The OAuth resource server is the component responsible for validating an incoming OAuth access token. At runtime, the resource server can retrieve session information associated with the token presented by the application from the token management layer. The resource server will look at the scope and determine whether or not the API call should be authorized or not. When access control is completely assigned to the API Management infrastructure, the resource server makes all the authorization decisions, then passes the API call to the backend API endpoint but in this case, the backend API has its own authorization mechanism. To accommodate this mapping requirement, the resource server retrieves the internal token associated with the access token presented by the mobile application and injects it to the API call to the backend service.