OAuth clients: Technical information, URLs, and code snippets

Here is a summary of all technical information, URLs, and code snippets relating to the authentication process for OAuth clients.

Use a Library: Do not perform these steps yourself. Use a library to support you through the process. OAuth client libraries are available for all popular programming languages and frameworks. This way, you can reduce implementation times to a minimum. If you use a library, in many cases you will only need to enter a few things (for example, OAuth URLs, the grant type, the client ID and secret) to set up your OAuth clients on the integration.

OAuth-specific URLs

Inxmail provides an OpenID Connect discovery endpoint. The endpoint is publicly accessible and returns a JSON object containing general information about the structure and configuration of Inxmail user management as a response. This includes, among other things, all relevant OAuth endpoints.

Note: Inxmail user management provides all tokens as signed JWT tokens. The JWKS endpoint provides the public keys to verify the signature of a token.

Authorization Code Grant Flow

Initiating the Authorization Code Grant

The Authorization Code Grant is initiated by calling the authorization URL(authorization request).

Example:

1
2
3
4
5
6
https://my.inxmail.de/auth/realms/nxp/protocol/openid-connect/auth
    ?response_type=code
    &scope=offline_access 
    &client_id=<client_id>
    &redirect_uri=<redirect_uri>
    &state=<custom state>

Details and links

Parameter	Description and links
response_type	Authorization Code Grant used. Must contain the value 'code'.
client_id	Client ID of the integration. You will receive the client ID when creating your OAuth client in Inxmail.
state	Optional: Use the state parameter to query the state between authorization request and authorization response.
redirect_uri	Redirect URL of the integration. Specify the same redirect URL you also entered in your OAuth client in Inxmail.
scope	OAuth scopes used. Must contain the value 'offline_access' in order for you to request a persistent refresh token.

Completing the Authorization Code Grant

The Authorization Code Grant is completed by redirecting the Inxmail user (following successful authentication) to the redirect URL (parameter 'redirect_uri') stored in the authorization request of the integration application(authorization response).

Example:

https://<redirect_uri des Authorization Request>
    ?code=<code>
    &state=<state des Authorization Request>

Details and links

Parameter	Description and links
code	Temporary string generated by the authorization server. The code parameter is used to request a refresh token via a token request.
state	Unchanged content of the state parameter from the authorization request.

Retrieving the State between the Authorization Request and Authorization Response

Before Inxmail User Management sends the redirect to the redirect URL (following successful user authentication), the state parameter is appended to the redirect URL unchanged. You can use the state parameter to obtain application-specific data of an integration between the authorization request and authorization response. If you want to query multiple state values, you will need to program them in the state parameter, for example, using a unique separator. You cannot enter the state parameter more than once.

To protect your integration from CSRF attacks, we recommend that you also assign a unique value (CSRF token) for each authorization request to the state parameter and verify it in the corresponding authorization response.

Requesting a Refresh Token

You can use the code parameter provided in the authorization response to request a refresh token for the integration via a token request. Since the code parameter is non-persistent, you should run the token request immediately after or during the authorization response.

https://my.inxmail.de/auth/realms/nxp/protocol/openid-connect/token
    ?grant_type=authorization_code
    &client_id=<client_id>
    &client_secret=<client_secret>
    &redirect_uri=<redirect_uri>
    &code=<code>

Details and links

Parameter	Description
grant_type	Type of grant used: Must contain the value 'authorization_code'.
client_id	Client ID of the integration. You will receive the client ID when creating your OAuth client in Inxmail.
client_secret	Client secret of the integration. You will receive the client secret when creating your OAuth client in Inxmail.
code	Unchanged content of the code parameter from the authorization response.
redirect_uri	Redirect URL of the integration. Must match the value of the redirect_uri parameter supplied in the previous authorization request.

The response of the token request contains, among other things, a refresh token that can be stored by the integration application in order to request new access tokens for an Inxmail user at a later time.

Example:

1
2
3
4
5
{
    "access_token":"<access_token>",
    "refresh_token":"<refresh_token>",
    ...
}

Access Token: The token response contains an up-to-date access token that you can use immediately.

Refresh Token Flow

Requesting an Access Token via a Refresh Token

Once a refresh token is available to the integration application, it can request a new access token for a user on its own without further user interaction.

Example:

https://my.inxmail.de/auth/realms/nxp/protocol/openid-connect/token
    ?grant_type=refresh_token
    &client_id=<client_id>
    &client_secret=<client_secret>
    &refresh_token=<refresh_token>

Details and links

Parameter	Description
grant_type	Grant type used. Must contain the value 'refresh_token'.
client_id	Client ID of the integration. You will receive the client ID when creating your OAuth client in Inxmail.
client_secret	Client secret of the integration. You will receive the client secret when creating your OAuth client in Inxmail.
refresh_token	Refresh token for which you wish to request a new access token.

The response to the token request contains, among other things, an up-to-date access token that can be used for an authenticated call of the Inxmail API on behalf of a user.

Example:

{
    "access_token":"<access_token>",
    ...
}

Further Information