Device Authorization Flow With PKCE

This section describes how to implement the Device Authorization Flow with Navigraph API. For general information about this type of authentication, see RFC 8628 - OAuth 2.0 Device Authorization Grant.

This is the recommended flow to use for desktop applications and in-process applications such as flight simulator add-ons. It is lightweight and does not have external dependencies on system browsers and callbacks. Works in any environment that can fetch data using https, including Microsoft Flight Simulator. Ideal for deployment to multiple targets including consoles and other keyboard-less devices.

For web and mobile applications it might be more convenient to use the Authorization Code flow.

OverviewRead the “Overview” section

1. The user initiates the authentication.

2. The application requests authorization from the Navigraph Identity Server using its Client ID and Client Secret.

3. The Navigraph Identity Server responds with a device_code, user_code, verification_uri, verification_uri_complete expires_in (lifetime in seconds for device_code and user_code), and polling interval.

4. The application asks the user to authorize the app. The application needs to provide atleast one of the following methods:

   • in environments that has access to the default browser, navigate to verification_uri_complete
   • asking the user to interact with a QR Code generated from the verification_uri_complete
   • display the user_code on-screen and ask the user to visit the verification_uri to enter the code manually

5. The application begins polling the Navigraph Identity Server for an Access Token) using the time period specified by interval. The application continues polling until either the user completes authentication flow or the user code expires.

6. The user authenticates using one of the configured login options (4) and may see a consent page listing the requested permissions.

7. When the user successfully completes the authentication flow, the Navigraph Identity Server responds with an Access Token and a Refresh Token.

8. 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

The client initiates the Device Authorization Flow by requesting a set of verification codes from the authorization server by issuing an HTTP POST request to the device authorization endpoint. The following parameters should be included by using the application/x-www-form-urlencoded format, with a character encoding of UTF-8 in the HTTP request entity-body:

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

client_id=<client-id>&client_secret=<client-secret>&code_challenge=<code_challenge>&code_challenge_method=S256

Parameters for /connect/deviceauthorizationRead the “Parameters for /connect/deviceauthorization” section

Successful deviceauthorization responseRead the “Successful deviceauthorization response” section

On successful response the following JSON structure is returned:

{
  "device_code": "kGUXxCuykgN0MV4PrsyARH360sfGrPZ8",
  "verification_uri": "https://navigraph.com/code",
  "verification_uri_complete": "https://identity.api.navigraph.com/code/default.aspx?user_code=THRGZFC6",
  "user_code": "THRGZFC6",
  "expires_in": 1800,
  "interval": 5
}

(On errors the authorization server responds in the same way as the token endpoint specified in Section 5.2 of [RFC6749].)

Your application should now instruct the user to use a browser to navigate to the uri given in verification_uri. As a quicker way of authenticating you are recommended to also convert the verification_uri_complete into a QR-code and display for the user who could directly authenticate using a mobile device.

The user will be asked by our servers to give consent for your application to approve or deny the request to authorize your application. Once this process is complete the user will be instructed to return to your application.

At the same time as you wait for the user to authorize the application you need to start a polling-scheme to be able to react on the authorization that the user is performing on our server. You do this by issuing periodical HTTP POST requests to our token-endpoint, with the interval given from the /connect/deviceauthorization endpoint in seconds:

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

grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=kGUXxCuykgN0MV4PrsyARH360sfGrPZ3JNA&code_verifier=<code_verifer>&client_id=<client-id>&client_secret=<client-secret>&scope=openid charts offline_access

Parameters for /connect/tokenRead the “Parameters for /connect/token” section

Error responsesRead the “Error responses” section

These are the errors that you can expect from the /connect/token endpoint

Successful token responseRead the “Successful token response” section

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjA0X3JsNjNvV2ZBSVc3WEd4UWUzQzVEY3dkTSIsImtpZCI6IjA0X3JsNjNvV2ZBSVc3WEd4UWUzQzVEY3dkTSJ9.eyJpc3MiOiJodHRwczovL2lkZW50aXR5LmFwaS5uYXZpZ3JhcGguY29tIiwiYXVkIjoiaHR0cHM6Ly9pZGVudGl0eS5hcGkubmF2aWdyYXBoLmNvbS9yZXNvdXJjZXMiLCJleHAiOjE2MTE1MTA2MjQsIm5iZiI6MTYxMTUwNzAyNCwiY2xpZW50X2lkIjoiZmJ3LWEzMm54Iiwic2NvcGUiOlsiY2hhcnRzIiwiZm1zZGF0YSIsIm9mZmxpbmVfYWNjZXNzIiwib3BlbmlkIl0sInN1YiI6ImM3YTIwY2JlLTU4ZjQtNDA3ZS1hZjJmLTVjODRmMTE5YzJlNiIsImF1dGhfdGltZSI6MTYxMTUwNzAyNCwiaWRwIjoiaWRzcnYiLCJ1cGRhdGVkX2F0IjoxNjA3MDgzNDI0LCJ0ZW5hbnQiOiJkZWZhdWx0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoibTRya3VzIiwiZW1haWwiOiJtYXJrdXNAZ3JhbmRub2lzZS5zZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJnaXZlbl9uYW1lIjoiTWFya3VzIiwiZmFtaWx5X25hbWUiOiJIYW1idXJnZXIiLCJwbGF5X3JvbGUiOiJ1c2VyIiwiYmV0YSI6InRydWUiLCJsb2ciOiJkZWJ1ZyIsImVtYWlsX2JvdW5jZWQiOiIwIiwiZW1haWxfbWFuYWdlX2tleSI6IjA0MjBGMURGLUU0MzMtNEFBMC1BRjBBLTBDNTg3QzU4MTZEQSIsInJvbGUiOiJhZG1pbiIsInRvcyI6IkZhbHNlIiwiZW1haWxfc2V0dGluZyI6IjAiLCJuYW1lIjoibTRya3VzIiwiYW1yIjpbInVybjppZXRmOnBhcmFtczpvYXV0aDpncmFudC10eXBlOmRldmljZV9jb2RlIl0sImFkZHJlc3MiOnsiY291bnRyeSI6IlNFIn19.nbG-Lu_87Z0nSVuPByrBowfX7rRLuHEVKHH7vjIpISBtm4Hh4pF4zjuTgL9xrRb70cPxcKoqEsY48lur-vED34bAspZda4tuLzH9NYHlF7FSgPVxxXpVP65KOG1wJwsSjFEsVkQzq8N6GeM0iqbevpZM-lXHijgAqgINJ-X4_P5YHbryMKVlWJv8mBNgUU3TQ0RHcChCEcRnAgRne0noxskSv3FD__UUmhAQxWyTMW7rFd0jIkB5pIEw5uIyZEz-uXReshDiZgA1_knSYb36XrnpYT0kRoao92Jw6MfLrtL8CV33W-G4aYZjBJRrIvstTSyukF7s0oh5gmhCibYQvA",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "399045b904e1d5b515c2d3de5a1fcd7c"
}

Congratulations! You have now finished the device-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 device flow again.