Resource Owner Password Credentials Grant
This authentication method is based on the Oauth2 resource owner password credentials grant method.
The resource owner password credentials grant allows a client to authenticate using the resource owner credentials. To use this grant both a client credential set and a resource owner credential set must be used.
The client credential can be retrieved from Meriworks and must be activated by an administrator for the ImageVault installation that the client should be able to connect to.
The resource owner credentials is the username/password that a user uses to authenticate to accesss ImageVault.
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.
Note
You can also request a client identity from Meriworks for embedding in your application.
You also need to supply the username and password of the resource owner. The following parameters must be supplied.
| Parameter Name | Description |
|---|---|
| grant_type | Defines the type of grant to be requested. Must be set to "password". |
| username | The resource owner username |
| password | The resource owner password |
Every parameter is provided as urlencoded form data (application/x-www-form-urlencoded)
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 czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=johndoe&password=A3ddj3w
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 |
| refresh_token | [Optional] The refresh token, which can be used to obtain new access tokens. |
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,
"refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}
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 irlfrfq4x32uh20xji6w
Content-Type: application/json; charset=UTF-8
{}
Refreshing an access token
If the authorization server issued a refresh token to the client, the client makes a refresh request to the token endpoint by adding the following parameters as urlencoded form data (application/x-www-form-urlencoded).
| Parameter Name | Description |
|---|---|
| grant_type | Defines the type of grant to be requested. Must be set to "refresh_token". |
| refresh_token | The refresh token issued to the client. |
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 czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
Because refresh tokens are typically long-lasting credentials used to request additional access tokens, the refresh token is bound to the client to which it was issued.
The response from an Refresh token request is the same as an ordinary access token response.
The authorization server MAY issue a new refresh token, in which case the client MUST discard the old refresh token and replace it with the new refresh token. The authorization server MAY revoke the old refresh token after issuing a new refresh token to the client.