Oauth2
Oauth2 with Sesamy
OAuth is an open standard to authorization. OAuth provides client applications a ‘secure delegated access’ to server resources on behalf of a resource owner. It specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials.
A technical specification of OAuth 2.0 is described in the standard RFC 6749. A non-technical simple specification is given in this guide and Wikipedia.
Grant types
The services supports three different grant types:
- Implicit Grant. Used for single page applications and web components.
- Code Grant. Used for web servers, apps and integrations.
- Client Credentials. User for services and not for requests on behalf of a user.
State
When creating Oauth2 requests it's possible to pass a state to the request which serves two functions. When the user is redirected back to your app, whatever value you include as the state will also be included in the redirect.
This gives your app a chance to persist data between the user being directed to the authorization server and back again, such as using the state parameter as a session key. This may be used to indicate what action in the app to perform after authorization is complete, for example, indicating which of your app’s pages to redirect to after authorization.
The state parameter also serves as a CSRF protection mechanism if it contains a random value per request. When the user is redirected back to your app, double check that the state value matches what you set it to originally.
Implicit Grant
With the implicit grant flow the user is redirected from the login form to the publishers website with the token passed as query string.
A implicit authentciation flow is initiated by redirecting the user to the login service:
https://token.sesamy.com/authorize?client_id=YOUR_CLIENT_ID&response_type=token&scope=openid&state=STATE&redirect_uri=REDIRECT_URI
The following query properties are available:
- client_id (required)
- response_type (required). Needs to be set to token.
- scope (required). A set of scopes that the generating token will have. See scopes for more info.
- redirect_uri (required). The url where the user will be redirected once the authentication is completed.
- state (optional). Pass a state that will be returned in the redirect querystring.
Once a user is authenticated the user will be redirected back to the specified redirect_uri with the token and expires_in as additional query string parameters:
https://example.com/some-page?token=ACCESS_TOKEN&expires_in=86000
The request will return the following response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token":"eyJz93a...k4laUWw",
"token_type":"Bearer",
"expires_in":86400
}
The generated token is valid for 24 hours.
Code Grant
The code grant flow works similar to the implicit grant flow, but instead of returning the access token directly to the browser a code is returned. This code can be resolved to a token using the client_secret.
A authorization code grant flow is initiated by redirecting the user to the login service:
https://token.sesamy.com/authorize?client_id=YOUR_CLIENT_ID&response_type=code&scope=openid&state=STATE&redirect_uri=REDIRECT_URI
The following query properties are available:
- client_id (required)
- response_type (required). Needs to be set to code.
- scope (required). A set of scopes that the generating token will have. See scopes for more info.
- redirect_uri (required). The url where the user will be redirected once the authentication is completed.
- state (optional). Pass a state that will be returned in the redirect querystring.
Once a user is authenticated the user will be redirected back to the specified redirect_uri with the code as additional query string parameters:
https://example.com/some-page?code=AUTHORIZATION_CODE
The code is valid for 15 minutes and can only be used once.
Exchange authorization code for an access token
To exchange the authorization code for an access token, the app makes a POST request to the token endpoint:
POST https://token.sesamy.com/oauth/token
Content-Type: application/x-www-form-urlencoded
client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=CODE&grant_type=authorization_code
The request will return the following response:
HTTP/1.1 200 OKContent-Type: application/json{ "access_token":"eyJz93a...k4laUWw", "token_type":"Bearer", "expires_in":86400}
Client Credentials
The Client Credentials grant is used when applications request an access token to access their own resources, not on behalf of a user.
A client can retrieve an access token by making a POST request to the token endpoint:
POST https://token.sesamy.com/oauth/token
Content-Type: application/x-www-form-urlencoded
client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=SCOPES&grant_type=client_credentials
The following query properties are available:
- client_id (required)
- client_secret (required)
- grant_type (required). Needs to be set to client_credentials.
- scope (required). A set of scopes that the generating token will have. See scopes for more info.
The request will return the following response:
HTTP/1.1 200 OKContent-Type: application/json{ "access_token":"eyJz93a...k4laUWw", "token_type":"Bearer", "expires_in":86400}