We have implemented the OAuth flow authorization_code grant type to support a simple way of authenticating Flixcheck users that try to request resources via third party apps.

Preconditions

The third party application that should be able to send requests as a representative must be added as an OAuth Client to the Flixcheck system.

Exchange authorization code for jwt token

Using a predefined flow of the third party app

To authorize the third party application, an authenticated user must grant access. For this purpose we implemented a page inside the portal app. Typically the third party application manages this process and requires the admin to add a link where the user can grant access. The page is available at app.flixcheck.com/portal/oauth/authorize?clientId=[clientId]&scope=readwrite&redirectUri=[redirectUri]&response_type=code&state=open and the query parameters clientId and redirectUri should be set by the third party application.

After the authenticated user grants access by clicking the primary button, we create an authorization code on our end that is returned to the third party application via the defined redirectUri in the query parameter code. The third party application will then send another server request to exchange the code for a signed jwt token, which enables authentication of subsequent requests.

Using api requests

Send a server request (POST) with an active session to /user/v7/oauth-codes having the following request body:

interface OAuthCodeCreateRequest {
		resource: {
				clientId: string
		}
}

Next send a new server request (POST) to /guest/v7/oauth-tokens having the following request body:

interface OAuthTokenCreateRequest {
		grant_type: "authorization_code";
		code: string;
		client_id: string;
		client_secret: string;
}

If the sent code is valid you’ll receive a signed jwt token (and a refresh token) in exchange and can authenticate your subsequent server requests by adding the following header:

Authorization: Bearer [TOKEN]

Our jwt tokens have a TTL of 60 minutes and can be refreshed by sending a server request (POST) to /guest/v7/oauth-tokens having the following request body:

interface OAuthTokenRefreshRequest {
    grant_type: "refresh_token";
    refresh_token: string;
    client_id: string;
    client_secret: string;
}

Managing connections

Users can manage their connections in the portal apps settings at “Connections” (”Verbindungen”). Available OAuth Clients and active connections are listed populated with information about who granted access and when access has been granted. An active connection can be revoked in the settings, too.