Resource Owner Password Credentials Grant Flow
Summary
The resource owner password credentials grant is suitable for clients capable of obtaining the resource owner’s credentials (username and password, typically using an interactive form). This implies that the resource owner has a trust relationship with the client application, such as the device operating system or a highly privileged application.
Agate’s implementation of this flow is very limited. The access token obtained with this flow does not provide authorization to access the resource applications. This flow’s main use case is to authenticate the resource owner.
Access Token Issuing
Request
The REST end point to be used is:
POST https://agate.example.org/ws/oauth2/token
The form parameters to be sent within the body of the request are:
Parameter |
Description |
---|---|
|
Client application name (required). |
|
Client application secret key (required). |
|
The expected value is: password (required). |
|
The user name. |
|
The user password. |
Response
The response is a JSON object with the following properties:
Property |
Description |
---|---|
|
The access token. Agate provides signed tokens that implement the JSON Web Token specification. |
|
What you can do with this token; in the case of Agate the value for this property is bearer. |
|
Information about the expiration time (in seconds) before the token expires. |
An example of response would be:
{
"access_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJlZGl0b3IiLCJpc3MiOiJhZ2F0ZTo1NmZjMzg0MmNjZjJjMWM3ZWM1YzVkMTQiLCJpYXQiOjE0NTk0NTg0NTgsImV4cCI6MTQ1OTQ4NzI1OCwianRpIjoiNTZmZDkxOWFjY2YyYzFjN2VjNWM1ZDE2IiwiYXVkIjpbIm1pY2EiLCJ0b3RvIl0sImNvbnRleHQiOnsic2NvcGVzIjpbIm1pY2EiXSwidXNlciI6eyJuYW1lIjoiSnVsaWUiLCJncm91cHMiOlsibWljYS1lZGl0b3IiXSwiZmlyc3RfbmFtZSI6Ikp1bGllIn19fQ.PqlLSZegdPLM2byp0jsgWV-XM3Xed8DP4I03kbUUEeo",
"token_type": "bearer",
"expires_in": 28799
}
Being a JSON Web Token (JWT), the access token can be decoded. There are three parts in a JWT: the header, the payload and the signature. This could give for example:
{
"alg": "HS256"
}
.
{
"sub": "editor",
"iss": "agate:56fc3842ccf2c1c7ec5c5d14",
"iat": 1459458458,
"exp": 1459487258,
"jti": "56fd919accf2c1c7ec5c5d16",
"aud": [
"client_app"
],
"context": {
"user": {
"name": "Julie LaTendresse",
"groups": [
"mica-editor"
],
"first_name": "Julie",
"last_name": "Latendresse"
}
}
}
.
[signature]
The JWT payload contains some basic details on the subject (in addition to the standard claims). These are available in the context object (which is a claim specific to Agate). The properties of the context are:
Property |
Description |
---|---|
|
The user full name for display. |
|
The user first name (if any). |
|
The user last name (if any). |
|
The user groups. |
Note that this step can be repeated as many times as necessary, using the same authorization code that was granted at step 1.
Errors
When an error is encountered during this step, the JSON object returned contains the description of the error, for example:
{
"error_description":"Authorization with code '3b1d664fb09407972d4c212081789c6f' does not exist",
"error":"NoSuchAuthorizationException"
}