Authorization
Connections to AOP and usage of the API are only allowed for authorized parties. So, before establishing a Websocket IPC connection the here described authorization steps are required to obtain an access token.
💡In case of integrated components which are started by the AOP App itself, a valid token is provided beforehand, e.g. by passing it by command line, and the authorization steps can be skipped.
To facility secure user and app authorization the OAuth 2.0 standard (RFC6749) is used.
Usage
The AOP app provides two OAuth related endpoints:
- https://«AOP host:port»/oauth/authorize (further referred as the auth url)
- https://«AOP host:port»/oauth/token (further referred as the token url)
All parameters can either be url encoded (e.g. http://127.0.0.1/oauth/auth/?param1=value1¶m2=value2) or provided by posting a JSON object using the same keys and values.
Authorization request
Authorization begins by requesting a one time code from the auth url with the following parameters:
| Parameter | Required | Description |
|---|---|---|
| response_type | Yes | Denotes the kind of response expected. Currently, only code is supported. |
| client_id | Yes | The app’s ID. |
| redirect_uri | Yes | Url that will be called after successful authentication. |
| skill | No | Specifies the required data access. |
| state | No | Application specific data to be returned by the auth endpoint unmodified. |
| code_challenge | No | Only used with the PKCE Extension. |
| code_challenge_method | No | Only used with the PKCE Extension. |
| station | No | The number of the station that should be pre-selected in the OAuth login page. |
If the request was successful, the url specified in redirect_uri will be called containing the following url encoded parameters:
| Parameter | Description |
|---|---|
| code | If response_type was code this parameter contains the one time use authorization code that can be exchanged for an access token. |
| state | The unmodified State given when requesting authorization. |
Access token request
To receive an access token the one time code obtained in the previous step must now be provided to the token url. The following parameters can be included:
| Parameter | Required | Description |
|---|---|---|
| grant_type | Yes | Has to be authorization_code. |
| code | Yes | The one time authorization code. |
| client_id | Yes | The app ID that made the authorization request. |
| redirect_uri | Yes | Url that was used when obtaining the authorization code. |
| code_verifier | No | Only used with the PKCE Extension. |
Upon success the endpoint will respond with an JSON object containing the following properties:
| Property | Type | Description |
|---|---|---|
| access_token | string | The access code. |
| refresh_token | string | Refresh token to (see Refresh token request for additional details). |
| token_type | string | Always Bearer. |
| expires_in | integer | Value in seconds until the access token expires. |
| station | string | The number of the station that was selected in the OAuth login page. Empty value if user chose to log in without occupying a station. In this case, the authorization grant is missing any station context and Functionality depending on that may not be available. |
The acquired access tokens are sender-constrained and can only be used when the containing JWT is signed by the requesting client’s private key.
Refresh token request
Refresh tokens can be used to acquire another access token once it expires without having to authorize again. To generate a new access token from a refresh token the token url is called with the following parameters:
| Parameter | Required | Description |
|---|---|---|
| grant_type | Yes | Must be refresh_token. |
| refresh_token | Yes | The one time authorization code. |
| client_id | Yes | The app ID that made the authorization request. |
The response is identically to the one from the Access token request and might also include a new refresh token to use for further requests.