<commit_before>---
order: 04
title: Mobile + API
image: /media/articles/architecture-scenarios/mobile-api.png
extract: Mobile Application which talks to an API. The application will use OpenID Connect with the Authorization Code Grant using Proof Key for Code Exchange (PKCE) to authenticate users.
description: Explains the architecture scenario with a mobile application client communicating with an API.
toc: true
---

# Mobile + API

In this scenario we will build a Timesheet API for a fictitious company named ABC Inc. The API will allow management of timesheet entries for an employee or a contractor.

We will also be building a Mobile Application which will be used to view and log timesheet entries in the centralized timesheet database using the API.


::: panel TL;DR
* Auth0 provides API Authentication and Authorizaion as a means to secure access to API endpoints (see [API Authentication and Authorization](#api-authentication-and-authorization))
* For authorizing a Mobile app user and granting access to the API, Auth0 supports the Proof Key for Code Exchange (see [Proof Key for Code Exchange](#proof-key-for-code-exchange-pkce))
* Both the Mobile app and the API must be configured in the Auth0 Dashboard (see [Auth0 Configuration](#auth0-configuration))
* The API is secured by ensuring that a valid Access Token is passed in the HTTP Authorization header when calls are made to the API (see [Implement the API](#implement-the-api))
* The Auth0.Android SDK can be used to authorize the user of the Mobile app and obtain a valid Access Token which can be used to call the API (see [Authorize the User](#authorize-the-user))
* The Mobile app can retrieve the user's profile information by decoding the ID Token (see [Get the User Profile](#get-the-user-profile))
* The Mobile app provides the Access Token in the HTTP Authorization header when making calls to the API (see [Call the API](#call-the-api))
* The Mobile app user's Access Token can be renewed to ensure the user does not have to log in again during a session (see [Renew the Token](#renew-the-token))
:::

## The Premise

ABC Inc. is a consulting startup company. Currently they have approximately 100 employees and they also outsource several activities to external contractors. All employees and external contractors are required to fill in their timesheets every week. 

The company has built a timesheets application, a scenario we covered in [Single Sign-On for Regular Web Apps](/architecture-scenarios/application/web-app-sso). The internal employees use this web app to fill in their timesheets but the company wants to replace it with a Mobile application. The app will be used to log timesheet entries and send the data to the centralized timesheet database using the API.

### Goals & Requirements

ABC wants to build a flexible solution. There are potential multiple clients which should be able to log timesheet entries, as well as batch processes which may upload timesheet entries from other, external systems.

Hence the company has decided to develop a single Timesheets API which will be used to log time not only by this Mobile Client, but by all other clients as well. They want to put in place a security architecture that is flexible enough to accommodate this. ABC Inc. wants to ensure that a large part of the code and business logic for the application can be shared across the different client applications.

It is required that only authorized users and applications are allowed access to the Timesheets API.

<%= include('../_includes/_api-overview-of-solution.md') %>

<%= include('../_includes/_api-authentication-and-authorization.md') %>

## Proof Key for Code Exchange (PKCE)

OAuth 2 provides several grant types for different use cases. In this particular use case, we want to access the API from a mobile application, which will use the OAuth 2.0 [Proof Key for Code Exchange](/api-auth/grant/authorization-code-pkce) to do so.

The [Authorization Code Grant](/api-auth/grant/authorization-code) has some security issues, when implemented on native applications. For instance, a malicious attacker can intercept the `authorization_code` returned by Auth0 and exchange it for an [Access Token](/tokens/access-token) (and possibly a [Refresh Token](/tokens/refresh-token)).

The Proof Key for Code Exchange (PKCE) (defined in [RFC 7636](https://tools.ietf.org/html/rfc7636)) is a technique used to mitigate this authorization code interception attack.

With PKCE, the Client creates, for every authorization request, a cryptographically random key called `code_verifier` and its transformed value called `code_challenge`, which is sent to Auth0 to get the `authorization_code`. When the Client receives the `authorization_code`, it will send the code and the `code_verifier` to Auth0's token endpoint to exchange them for the requested tokens.

![PKCE](/media/articles/architecture-scenarios/mobile-api/authorization-code-grant-pkce.png)

1. The native app initiates the flow and redirects the user to Auth0 (specifically to the [/authorize endpoint](/api/authentication#authorization-code-grant-pkce-)), sending the `code_challenge` and `code_challenge_method` parameters.
2. Auth0 redirects the user to the native app with an `authorization_code` in the querystring.
3. The native app sends the `authorization_code` and `code_verifier` together with the `redirect_uri` and the `client_id` to Auth0. This is done using the [/oauth/token endpoint](/api/authentication?http#authorization-code-pkce-).
4. Auth0 validates this information and returns an `access_token` (and optionally a `refresh_token`).
5. The native app can use the `access_token` to call the API on behalf of the user.

## Auth0 Configuration

In this section we will review all the configurations we need to apply at the [Auth0 Dashboard](${manage_url}/).
<commit_msg>Change example company name<commit_after>---
order: 04
title: Mobile + API
image: /media/articles/architecture-scenarios/mobile-api.png
extract: Mobile Application which talks to an API. The application will use OpenID Connect with the Authorization Code Grant using Proof Key for Code Exchange (PKCE) to authenticate users.
description: Explains the architecture scenario with a mobile application client communicating with an API.
toc: true
---

# Mobile + API

In this scenario we will build a Timesheet API for a fictitious company named ExampleCo. The API will allow management of timesheet entries for an employee or a contractor.

We will also be building a Mobile Application which will be used to view and log timesheet entries in the centralized timesheet database using the API.


::: panel TL;DR
* Auth0 provides API Authentication and Authorizaion as a means to secure access to API endpoints (see [API Authentication and Authorization](#api-authentication-and-authorization))
* For authorizing a Mobile app user and granting access to the API, Auth0 supports the Proof Key for Code Exchange (see [Proof Key for Code Exchange](#proof-key-for-code-exchange-pkce))
* Both the Mobile app and the API must be configured in the Auth0 Dashboard (see [Auth0 Configuration](#auth0-configuration))
* The API is secured by ensuring that a valid Access Token is passed in the HTTP Authorization header when calls are made to the API (see [Implement the API](#implement-the-api))
* The Auth0.Android SDK can be used to authorize the user of the Mobile app and obtain a valid Access Token which can be used to call the API (see [Authorize the User](#authorize-the-user))
* The Mobile app can retrieve the user's profile information by decoding the ID Token (see [Get the User Profile](#get-the-user-profile))
* The Mobile app provides the Access Token in the HTTP Authorization header when making calls to the API (see [Call the API](#call-the-api))
* The Mobile app user's Access Token can be renewed to ensure the user does not have to log in again during a session (see [Renew the Token](#renew-the-token))
:::

## The Premise

ExampleCo is a consulting startup company. Currently they have approximately 100 employees and they also outsource several activities to external contractors. All employees and external contractors are required to fill in their timesheets every week. 

The company has built a timesheets application, a scenario we covered in [Single Sign-On for Regular Web Apps](/architecture-scenarios/application/web-app-sso). The internal employees use this web app to fill in their timesheets but the company wants to replace it with a Mobile application. The app will be used to log timesheet entries and send the data to the centralized timesheet database using the API.

### Goals & Requirements

ExampleCo wants to build a flexible solution. There are potential multiple clients which should be able to log timesheet entries, as well as batch processes which may upload timesheet entries from other, external systems.

Hence the company has decided to develop a single Timesheets API which will be used to log time not only by this Mobile Client, but by all other clients as well. They want to put in place a security architecture that is flexible enough to accommodate this. ExampleCo wants to ensure that a large part of the code and business logic for the application can be shared across the different client applications.

It is required that only authorized users and applications are allowed access to the Timesheets API.

<%= include('../_includes/_api-overview-of-solution.md') %>

<%= include('../_includes/_api-authentication-and-authorization.md') %>

## Proof Key for Code Exchange (PKCE)

OAuth 2 provides several grant types for different use cases. In this particular use case, we want to access the API from a mobile application, which will use the OAuth 2.0 [Proof Key for Code Exchange](/api-auth/grant/authorization-code-pkce) to do so.

The [Authorization Code Grant](/api-auth/grant/authorization-code) has some security issues, when implemented on native applications. For instance, a malicious attacker can intercept the `authorization_code` returned by Auth0 and exchange it for an [Access Token](/tokens/access-token) (and possibly a [Refresh Token](/tokens/refresh-token)).

The Proof Key for Code Exchange (PKCE) (defined in [RFC 7636](https://tools.ietf.org/html/rfc7636)) is a technique used to mitigate this authorization code interception attack.

With PKCE, the Client creates, for every authorization request, a cryptographically random key called `code_verifier` and its transformed value called `code_challenge`, which is sent to Auth0 to get the `authorization_code`. When the Client receives the `authorization_code`, it will send the code and the `code_verifier` to Auth0's token endpoint to exchange them for the requested tokens.

![PKCE](/media/articles/architecture-scenarios/mobile-api/authorization-code-grant-pkce.png)

1. The native app initiates the flow and redirects the user to Auth0 (specifically to the [/authorize endpoint](/api/authentication#authorization-code-grant-pkce-)), sending the `code_challenge` and `code_challenge_method` parameters.
2. Auth0 redirects the user to the native app with an `authorization_code` in the querystring.
3. The native app sends the `authorization_code` and `code_verifier` together with the `redirect_uri` and the `client_id` to Auth0. This is done using the [/oauth/token endpoint](/api/authentication?http#authorization-code-pkce-).
4. Auth0 validates this information and returns an `access_token` (and optionally a `refresh_token`).
5. The native app can use the `access_token` to call the API on behalf of the user.

## Auth0 Configuration

In this section we will review all the configurations we need to apply at the [Auth0 Dashboard](${manage_url}/).

{'fraction_non_alphanumeric': 0.06276650179089203, 'fraction_numerical': 0.006140201262152482, 'mean_word_length': 4.878195488721804, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4889655', 'n_tokens_mistral': 3015, 'n_tokens_neox': 2840, 'n_words': 1610}