1. /Authentication
  2. /Authorization Code Flow with PKCE

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:<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>

client_idClient IDThe Client ID is the id for your client/application which you will obtain from Navigraph.
response_typecodeRequests Authorization Code Flow.
staterandom string (minimum 11 chars )The Navigraph Identity Server will echo back the state value on the token response, this is for round tripping state between client and provider, correlating request and response and CSRF/replay protection
scope"openid offline_access"Scopes enable your application to access specific API endpoints on behalf of a user. The set of scopes you pass in your call determines the access permissions that the user is required to grant. For FMS Data add "fmsdata" and for charts add "charts".
redirect_uriURI to redirect toThe URI to redirect to after the user grants or denies permission. You need to agree with Navigraph what URI you want to direct to as a 100% match is needed for the flow to succeed.
code_challenge43 character Code ChallengePKCE code_challenge read more about how to generate it here.
code_challenge_method"S256"PKCE hashing method (SHA256).

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, contains the following parameters:

Query ParameterDescription
codeAn authorization code that can be exchanged for an Access Token.
stateThe value of the state parameter supplied in the request.

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:

Request ParameterValue
grant_typeThis field must contain the value "authorization_code".
codeThe authorization code
redirect_uriThe value of this parameter must exactly match the value of redirect_uri supplied when requesting the authorization code.
client_idThe Client ID
client_secretThe Client Secret
code_verifierThe PKCE code verifier.

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
Content-Type: application/x-www-form-urlencoded


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.