Authorization Code Flow with PKCE

This section describes how to implement the Authorization Code flow with Navigraph API. For general information about this type of authentication, see IETF RFC-7636.

This is the most advanced OIDC flow and is recommended for web and mobile applications. For desktop, console and in-process applications such as flight simulator add-ons the Device Authorization Flow is recommended.

OverviewRead the “Overview” section

1. The user initiates the authentication.

2. The application sets up a callback for the default browser to redirect to. This is typically achieved by setting up a TCP/IP listener on localhost or using a custom URI scheme.

3. The application generates an authorization URI from the Client ID and opens it in the system default browser, redirecting the user to the Navigraph Identity Server.

4. The user authenticates and may see a consent page listing the permissions requested.

5. The Navigraph Identity Server redirects the user back to the application using the method in (2) with an authorization code which is a not-more-than-once token for single use. It has a short lifespan (usually less than 30 seconds).

6. The application exchanges the code for an Access Token and a Refresh Token using the /token-endpoint on the Navigraph Identity server along with the application's Client ID and Client Secret.

7. The application can now use the Access Token to access the Navigraph API and the Refresh Token to get new tokens periodcially.

AuthenticationRead the “Authentication” section

Creating the Authorization URIRead the “Creating the Authorization URI” section

The client initiates the Authentication Code flow by opening the authorization_uri in the external default browser. The authorization_uri by combining the /connect/authorize endpoint URI with the following query parameters:

https://identity.api.navigraph.com/connect/authorize?client_id=<client_id>&response_type=code&state=<state>&scope=openid offline_access fmsdata&redirect_uri=<redirect_uri>&code_challenge=<code_challenge>&code_challenge_method=<code_challenge_method>

The user will then login to his account on the Navigraph Identity Server where also consent is given for the permissions (scopes) that the application is requesting to use on the users behalf. When the user completes the authentication the Navigraph Identity Server will redirect the user back to the application using the specified redirect_uri.

Receiving the Authorization CodeRead the “Receiving the Authorization Code” section

If the user accepts your request, the response query string, for example https://example.com/callback?code=KJMsmsjAJmamslwNSOL&state=12hjdsd02ndk, contains the following parameters:

The state value should be verified to equal the state that was included in the authorization_uri, if this is not the case there authentication flow should be cancelled.

Exchanging the code for tokensRead the “Exchanging the code for tokens” section

When the authorization code has been received, you should exchange it for an Access Token and Refresh Token by making a POST request to the /connect/token endpoint of the Navigraph Identity Server. The body of this POST request must contain the following parameters encoded in application/x-www-form-urlencoded:

Successful token responseRead the “Successful token response” section

The Navigraph Identity Server will now return a response similar to this:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjA0X3JsNjNvV2ZBSVc3WEd4UWUzQzVEY3dkTSIsImtpZCI6IjA0X3JsNjNvV2ZBSVc3WEd4UWUzQzVEY3dkTSJ9.eyJpc3MiOiJodHRwczovL2lkZW50aXR5LmFwaS5uYXZpZ3JhcGguY29tIiwiYXVkIjoiaHR0cHM6Ly9pZGVudGl0eS5hcGkubmF2aWdyYXBoLmNvbS9yZXNvdXJjZXMiLCJleHAiOjE2MTcyODAwNTIsIm5iZiI6MTYxNzI3NjQ1MiwiY2xpZW50X2lkIjoid2Vic2l0ZS13ZWIiLCJzY29wZSI6WyJvcGVuaWQiLCJlbWFpbCIsInVzZXJpbmZvIiwicm9sZXMiLCJvZmZsaW5lX2FjY2VzcyJdLCJzdWIiOiI4YWI2YWM2NS1kZGNhLTQ1N2UtOGIzNy1lZjFlZjZjMWZhNTUiLCJhdXRoX3RpbWUiOjE2MTcyNzY0NTEsImlkcCI6Imlkc3J2IiwiZm1zZGF0YSI6InJlYWQiLCJhbXIiOlsicGFzc3dvcmQiXSwic3Vic2NyaXB0aW9ucyI6WyJmbXNkYXRhIiwiY2hhcnRzIl19.Qr2RD5LWgwMmgLp_5gwKWy73TDOU5H5BPFKnW4vcRnuM1sh9PE44VP3qzEAJ55q4tBDw25oXJiKUiV9MiRCiTHBoZpl2eDhT75z03nWlQFhcy4fJzeu8_hMY-syhBcYTHZwQqIG9uzuU09wIeBkeq5swVwbC7787KwopAr5GPSBEV939-fx-fHDhcPKMMItun-eZfJL9Ih315aidhgK3gJyNm6rZFuXbZ2x5pVf8Psf32THamu_fNXOZweT02z9ETTSZDAFtTgKdJKtI-oKxWJA0w3qwLs9Hqk9lzLUauJI7KzIrgQakrZJPUzBFrFwrjEq4mbDNf1F8rLfimf_lcw",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "399045b904e1d5b515c2d3de5a1fcd7c"
}

Congratulations! You have now finished the Authorization Code With PKCE flow. The following header should be added to all further requests to our API endpoints using the access-token you just recieved:

Authorization: Bearer <access_token>

Refreshing tokensRead the “Refreshing tokens” section

Without a valid access-token our servers will respond to your requests with HTTP 401 UNAUTHORIZED. The access-token has a limited lifetime of about 60 minutes. When it expires you need to fetch a new token. You do this with a simple call to our token-endpoint where you provide the refresh-token in return for a new access-token and a new refresh-token. The refresh-token can only be used once, so be sure to not only update your access-token but also your refresh-token for every refresh.

POST /connect/token/ HTTP/1.1
Host: identity.api.navigraph.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id=<client_id>&client_secret=<client-secret>&refresh_token=399045b904e1d5b515c2d3de5a1fcd7c

Notice that the refresh-token is long-lived, it is therefore recommended to use it the next time your user starts your application to retrieve tokens to avoid having the user manually login using the Authorization Code With PKCE again.