Authentication

To use Enturs privileged endpoints your application needs to be authenticated. The Entur APIs use Oauth2 authentication, specifically the Client Credentials Grant (https://oauth.net/2/grant-types/client-credentials/). This is intended for Server-to-Server (S2S) communication. In other words it is not intended for applications where credentials are accessible by end users. The client_id and client_secret are handled by the application, which it uses to gain authentication from Enturs authentication  service (AS). Communication to authenication servers enforce HTTPS.
 

Authenticationflow

Entur uses OAuth2 as an authentication service (AS), and Client Credentials Grant as authenticationflow. Client Credentials Grant allows an application to request an access token using client_id and client_secret provided by Entur. The application uses the access token when it makes requests against Entur APIs (RS). The token is validated on every request to the API, and an invalid token will result in a rejected request. The access token is a JWT and will be covered in details later. The following illustration is a high level description of the authenticationflow.


Illustration 1.1: Authenticationflow

  1. The application sends "client_id" and "client_secret" to the AS - Oauth2. 

  2. The AS validates the credentials and returns an access token on successful authentication.

  3. The application includes the access token in the request to Entur API.

  4. The APIs validates the access token, executes the action and/or returns the requested information.
     

Obtaining a Token

To obtain a token you need to request access by authenticating. Here you use "https://<SERVER>/oauth/token" where the "Server" is the authenticated domain. Your application needs to use the corresponding "Audience", which is a unique identifier that makes the access token a JWT. Your application will not get a token if the "Server" and "Audience" are not comparable.

Authentication server and audience available for Partners:

Environment

Server URL

Audience

Dev

partner.dev.entur.org

api.dev.entur.io

Staging

partner.staging.entur.org

api.staging.entur.io

Production

partner.entur.org

api.entur.io

Dev and Staging consist of data which is used for testing.

With the given information, and intention to get an access token to Development, we get:

  curl --request POST \
    --url https://partner.entur.org/oauth/token \
    --header 'content-type: application/json' \
    --data '{
      "client_id":" Q2xpZW50X0lE ",
      "client_secret": [SUPER SECRET],
      "audience":"https://api.entur.io",
      "grant_type":"client_credentials"
    }

There are several libraries available for authenticating your application. Here is a quickstarter for some applications provided by Enturs authentication service: https://auth0.com/docs/quickstart/backend.
 

The Access Token

The access token provided from Entur is a JWT (https://jwt.io/introduction/). A JWT (JSON Web Token) is a Base64-encrypted JSON-document. After authentication, your userless-application will use the JWT in the HTTP-header with authorization, each time it calls for services through the Entur API. 
This JWT contains three parts, divided by a punctuation ("."): Header, payload and signature. 
The structure is: <header>.<payload>.<signature>.

For more information on authentication with JWT: https://auth0.com/docs/tokens/reference/jwt/jwt-structure.
 

Using Access Tokens in Requests

After obtaining the access token (JWT) use it when you send request to the API.

 Authorization: Bearer <JWT token>‚Äč  

Under Authroization you add the whole Base64-encoded JWT here. Header, payload and signature all need to be presented, separated by punctuation.
The Entur APIs will validate the access token. Therefore it is imporant that you follow this semantic when requesting from the APIs. If your token is not valid for some reason, then it will be denied access.
 

Where to Save the Access Tokens

The application is required to securily store the access token inaccessible to end user. The Entur access token needs to be stored on the server side. Storing the access token locally is not recommended. For more information about saving tokens see: https://auth0.com/docs/security/store-tokens.
 

Re-Authentication

Access tokens are short lived and will expire after a certain amount of time. When the token expire you'll get an HTTP error when doing requests. Your application must be able to handle these error codes and do a re-authentication if and/or when this occurs. Ideally your application keeps track of when tokens expire by checking the exp claim, and re-authenticates before it expire. For more information about claims, see access token. Note: Re-authentication will take some time, so execute it some time before it expires. 
 

HTTP Error Messages

These error messages are from the APIs.

301: Moved Permanently  - The HTTP server was been moved permanently to a HTTPS server. This error is used for permanent URL redirection.

302: Redirect  - Attempts to connect to the Entur APIs with HTTP will end in a redirection. Make sure your server is HTTPS.

401: Unauthorized  - The request is lacking valid authentication. This may indicate that the “client_secret” has been changed or is not correct.

403: Forbidden  - If the scope claim does not include a request your application is trying to acces you will get this error. This may indicate that your application is wrongly configured or that you do not have the permissions needed for making changes to the specific endpoint. Ref. https://auth0.com/docs/api-auth/tutorials/verify-access-token#validate-t...  (“How can I check the permissions?”).

405: Method not allowed  - This might mean that your BFF is trying to connect to the server via HTTP, which the Entur API does not support.

408: Session timeout  - The access token has expired whle the session was ongoing. Reauthenticate the session and remember to check when the access token expires.
 

Troubleshooting

These errors are coming from the authentication service.

“Invalid grant” - This is a generic error message and may mean one of the following:

  • Wrong username and/or password
  • Username is from an invalid domain
  • Endpoint does not support “Resource Owner Password Credentials Grant”. Validate that you are using the “client_id” correctly.

“Unauthorized client”  - See “401: Unathorized”:

  • “client_secret” might have been changed. Check if it is the same.

Reference List

https://auth0.com/docs/api-auth/tutorials/verify-access-token#validate-t...
https://auth0.com/docs/tokens/use-access-tokens
https://auth0.com/docs/security/store-tokens
https://tools.ietf.org/html/draft-ietf-oauth-security-topics-11
https://jwt.io/introduction/
https://auth0.com/docs/api-auth/tutorials/verify-access-token#sample-imp...