oauth tutorial - OAuth Assertion - oauth2 tutorial - oauth authentication
What is Assertion?
- This specification provides a general framework for the use of assertions as authorization grants with OAuth 2.0.
- It is a package of information that makes sharing of identity and security information easier across various security domains.
- It holds the data about the subject, circumstances under which assertion is considered valid, such as where and when it can be used.
- Note: The use of assertions for client authentication is orthogonal to and separable from using assertions as an authorization grant.
- They can be used either in combination or separately.
They are two general types assertions are −
Bearer Assertions:
- Any entity can use assertion to obtain access to the associated resources, where in an entity can be in-charge of bearer assertion.
Holder-of-key Assertions:
- In this case, the entity must demonstrate the possession of additional cryptographic material, if it wants to access associated resources.
The following figure depicts the third party created assertion.
learn oauth tutorial - assertion - oauth example
Step 1 – In this first case, where the client first requests assertion from third party entity, which is usually known as the "token service" or "security token service". Token service is capable of issuing, renewing, validating, and transforming security tokens to the client.
Step 2 − The token service fulfils the client's request by granting assertion.
Step 3 − A trust relationship exists between the token service and the relying party. The client then issues assertion to the relying party.
Step 4 − The relying party validates assertion and notifies the client about the status.
The following figure depicts the self-issued assertion.
learn oauth tutorial - assertion label- oauth example
- This is the second case in which the client itself creates assertion locally. It doesn't have to request for assertion from the third party entity.
- The client then issues the created assertion to the relying party.
- The relying party validates assertion and notifies the client about the status.
Transporting Assertions:
- This section defines HTTP parameters for transporting assertions during interactions with a token endpoint of an OAuth authorization server.
- Because requests to the token endpoint result in the transmission of clear-text credentials (in both the HTTP request and response), all requests to the token endpoint MUST use Transport Layer Security (TLS), as mandated in Section 3.2 of OAuth 2.0
Using Assertions as Authorization Grants:
Using the following HTTP request parameters, the client includes the assertion and related information when using the assertions as authorization grants.
- grant_type
The format of the assertion that is defined by the authorization server.
- assertion
A particular serialization of the assertion defined by the profile documents.
- scope
The authorization of the token is previously granted through some out-ofband mechanism while exchanging the assertions for access tokens. In that case, the scope that is requested must be equal to or less than the original scope granted to the authorized accessor.
The following example demonstrates an assertion being used as an authorization grant (with extra line breaks for display purposes only):
POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer&
assertion=PHNhbWxwOl...[omitted for brevity]...ZT4
click below button to copy the code. By - oauth tutorial - oauth2 tutorial - team
- An assertion used in this context is generally a short-lived representation of the authorization grant, and authorization servers SHOULD NOT issue access tokens with a lifetime that exceeds the validity period of the assertion by a significant period.
- In practice, that will usually mean that refresh tokens are not issued in response to assertion grant requests, and access tokens will be issued with a reasonably short lifetime.
- Clients can refresh an expired access token by requesting a new one using the same assertion, if it is still valid, or with a new assertion.