This article describes how to make authenticated requests against our APIs.
Browser based requests
We are using OAuth2 for browser authenticatio. OAuth2 is described in RFC 6749. We are currently only using “authorization flow”. Please use our ac-authenticator-app in all client applications instead of implementing OAuth manually.
Every authenticated request from a browser must contain 3 headers:
- the clientId in “x-admiralcloud-clientid”
- the device in “x-admiralcloud-device”
- the token in “Authorization: Bearer”
Obtain clientId
The clientId is given you by our engineering team. Contact support if you want to start your application. The clientId must be used for login as well as for every subsequent request.
Device
The device identifier is a unique string that you have to create in your app. It should be unique for every user an device.
Obtain the token
In order to receive the token you have to perform a login request with username and password. The response contains a code with a very short lifetime.
Now, you have to send this code to our auth server and will retrieve a valid token in return. The code can only be used once, regardless of the outcome.
Make sure to monitor expiration time of the token. You can only obtain a new token (refreshed token) with a valid token. Once your token has timed out, you have to restart the authentication process.
Step-by-step procedure
An app – let’s name it “hello world app” (HWA) wants to access a restricted resource from the API (/v5/user/me). If no authentication data is sent or the authentication data is outdated, the API will return a HTTP 401 error.
- The ac-app-authenticator (ACAA) within ACC now makes a GET call to AUTH /authorize with client_id, callbackUrl, device, response_type “code”, state and version
- The AUTH server will respond with a redirect to our login platform (ACLOGIN), an external IDP (e.g. ADFS) or, if a valid cookie is present) continue with #6
- Lets assume the user is not yet logged in and so AUTH will redirect (HTTP 302) to ACLOGIN
- ACLOGIN displays the login form, the user enters his credentials and sends the data to AUTH /login via XHR
- The AUTH server responds to the XHR request with a JSON object containing an URL and the statusCode 302. ACAPP now must redirect (302) to that URL. The URL is the callback ACAA used during #1
- ACAPP within ACC now removes the CODE from the redirection URL and makes an XHR request to GET AUTH /token with client_id, device, callbackUrl, the CODE and grant_type “authorization_code”
- The AUTH server validates the code and the request and returns a JSON object with the accessToken, accessTokenExpiresAt, accessTokenExpires.
- ACAA within ACC now uses this accessToken to request the restricted resource from the API (v5/user/me). The call will be successful
Server based requests
TBC