Mobile API Gateway

Securing Mobile APIs using the OAuth2 Authorization Code Grant with PKCE

Use Case Description

For mobile applications (on smartphones/tablets) a typical use case is that you let a user log in to your service, or create some kind of unique identifier for the user's device, which is considered the identity of the user, and that you then allow access only in the context of this user to your backend API.

In order to prevent fraud or excessive usage of your API, it's also typical to apply rate limiting by number of calls per authorized user and application.

You can now leverage the "local" authentication method of wicked to store your mobile users email addresses and passwords. Wicked can act as a full featured identity provider for your mobile backend, i.e. be a full mobile backend, including authentication and authorization.


Development Time Workflow

For development time, the following workflow is typical:

  1. The developer signs up for the API Portal and registers the mobile application in the portal, using a trusted subscription
  2. The registered application should register a redirect URL which will, on the end user's device, open the installed application with a specific path (custom schemas, such as myapp:// are also allowed)
  3. By creating a subscription to the Mobile API, the developer obtains client credentials for the mobile application, a client ID and a client secret; for this use case, only the client ID is significant
  4. The developer incorporates the client ID into the mobile application and implements the needed bits for the OAuth2.0 Authorization Code Grant with the PKCE extension.

For the Authorization Code Grant to work with public clients (a client which is not running on a server backend), requires the PKCE extension to be implemented. Any deployed portal itself contains more information on the details on how to implement this, see e.g. the help pages of the wicked Demo portal.

Runtime Workflow

At runtime, the authentication and authorization of the API usage for the end user inside the mobile app will work as follows. When the end user opens the application for the first time, this happens:

  1. The mobile app shows a web view and redirects to the Authorization end point of the wicked Authorization Server (depending on which identity provider was configured)
  2. By checking the client ID of the authorization call, the Authorization Server knows which application is requesting access to the API, and can in turn verify the identity of the calling user (with whichever identity provider is configured)
  3. If the user identity was successfully established, the Authorization Sevrer now answers with a redirect back to the application, possibly using a custom schema, such as myapp://hello/world?code=abcdefabcdefabcdef.
  4. The application now uses the token and a PKCE code verifier to retrieve an access token and a refresh token, according to the standard OAuth 2.0 Authorization Code Grant.

All requests which the application now issues towards the API will be enriched with (a) the client identity, and (b) the end user's identity, passed on as headers.


How do I implement this with wicked?

Wicked packs brings all the necessary components to implement this out of the box, including the PKCE extension:

  • Wicked stores usernames and passwords, and if needed, can also ask new users for additional information (registration information). It can also federate any other supported Identity Provider, such as any SAML ot OAuth2 IdP, Google, GitHub,...
  • The wicked Authorization Server automatically creates suitable endpoints so that your API can only be accessed using access tokens which are created using this endpoint.
  • When your backend API is called from the Gateway Proxy, and a valid access token is presented, Kong will automatically inject who is calling (as X-Authenticated-UserId), which application is calling the API on behalf of the user.
  • You can leverage this injected information to do further checking on the user as your business logic requires, but wicked makes sure that only well-known users are being let through to your API.

In case you implement using node.js, you can also leverage the wicked SDK to have even more influence on the user and registration management. Read up on the wicked SDK here:

As mentioned, wicked supports the PKCE extension of the Authorization Code Grant (see RFC 7636) and OAuth2 for native apps (see RFC 8252).

Back to top

© 2016-2018 Haufe-Lexware GmbH & Co. KG,,,,