Client Credentials Grant
This authentication method is based on the Oauth2 client credentials grant method.
The client credentials grant uses the client (application) credentials to authenticate with ImageVault. You are authenticated as a client, not as an user. We have added an Impersonate addition to this specification to allow creating impersonated keys but we recommend that you use the Resource Owner Password Credentials Grant when possible.
Access token request
The client first requests an access token from the core server by providing user credentials using HTTP basic authentication. The user name/password to supply is the client identity that is registered in ImageVault Core. See managing client identities for more information.
It can also provide additional information like a user and roles that represents the user who the request should be impersonated as.
The call should be directed to the /apiv2/oauth/token service on the ImageVault server.
The content of the request can consist of a set of parameters
| Parameter Name | Description |
|---|---|
| grant_type | Defines the type of grant to be requested. Must be set to "client_credentials". |
| impersonate_claims | [Optional, from IV v5.18] The user claims to impersonate the call as, comma separated list of type=value |
| impersonate_as | [Obsolete from IV v5.18] The user name to impersonate the call as |
| roles | [Obsolete from IV v5.18] A comma separated list of roles to impersonate the call as |
Every parameter is provided as urlencoded form data (application/x-www-form-urlencoded)
Note
The impersonate_claims parameter was introduced in IV v5.18 and obsoletes the impersonate_as and roles parameters. The old parameters still works as before but any occurrance of the new parameter will supersede the old parameter values.
Example
For example, the client makes the following HTTP request using transport-layer security (with extra line breaks for display purposes only):
POST /apiv2/oauth/token HTTP/1.1
Host: server.example.com
Authorization: Basic bXl1c2VybmFtZTokZWNyMzdQQHNTdzByZA==
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
Access token response
If authentication is successful and all parameters are valid, then the service will return an access token on JSON format. The access token contains the following properties
| Parameter Name | Description |
|---|---|
| access_token | Contains the access token itself. |
| token_type | The type of token that was issued. |
| expires_in | The number of seconds that this token is valid |
Example
An example successful response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"Bearer",
"expires_in":3600
}
Further request
The received access token can then be used in coming requests to the core service until the token has expired. The access token is passed along using the Authorization (or IVAuthorization) http request headers. The value of the header is the token_type followed by a whitespace and then the access_token itself.
Example
The following example shows the usage of the Authorization header.
POST https://imagevault.local/apiv2/MediaService/Find HTTP/1.1
Host: imagevault.local:8001
Content-Length: 2
Cache-Control: no-cache
Pragma: no-cache
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Content-Type: application/json; charset=UTF-8
{}