Developer Resources

Get Tokens: Extension Grants

The extension grant type provides support for additional grant types extending the OAuth2.0 specifications. An example is the use of the SAML 2.0 Bearer extension grant. In this grant type, a SAML assertion (indicated by step 1 below, however the process used to acquire this SAML assertion is out of scope of this document) can be exchanged for an OAuth 2.0 access token (step 2).

Oauth saml flow
Capability

Browser-based end user interaction

No1

Can use external IDP for authentication

Yes2

Requires client authentication

No

Requires client to have knowledge of user credentials

No

Refresh token allowed

No

Access token is in context of end user

Maybe3

1 Although the grant type does not allow for user interaction, the process to generate the SAML assertion used in this flow can involve user interaction.

2 As long as the PingFederate AS is able to verify the SAML assertion, this assertion can be generated from a foreign STS.

3 Access token will be in the context of the subject of the SAML assertion, which may be an end-user a service or the client itself.

Sample Client Configuration

For the SAML bearer extension grant type example below, the following client information will be used:

Admin Label OAuth2 Parameter Example Value

Client ID

client_id

saml_client

Client Authentication

client_secret

2Federate

Allowed Grant Types

grant_type

grant_type of "urn:ietf:params:oauth:grant-type:saml2-bearer"

Getting a Token

At this stage, the client has a SAML assertion that it needs to exchange for an OAuth 2.0 access token. The process in which the client received the assertion is out of scope (i.e. bootstrap assertion, STS token exchange), however the client would Base64 URL encode the assertion and include it in a HTTP POST to the token endpoint.

For the example below, the following SAML assertion (abbreviated for readability) was received by the client and is are used to request an access token:

PHNhbWw6QXNzZXJ0aW9uIElEPSJTdXdCSDdiQjM3cWVmT0tycmlaZkc3Y09H
...
Pjwvc2FtbDpBc3NlcnRpb24-
POST https://localhost:9031/as/token.oauth2 HTTP/1.1

Content-Type: application/x-www-form-urlencoded

Authorization: Basic c2FtbF9jbGllbnQ6MkZlZGVyYXRl

grant_type= urn:ietf:params:oauth:grant-type:saml2-bearer&assertion=
PHNhbWw6QXNzZXJ0aW9uIElEPSJTdXdCSDdiQjM3cWVmT0tycmlaZkc3Y09H...Pjwvc2FtbDpBc3NlcnRpb24-&scope=edit
The client credentials can also be provided using the client_id and client_secret parameters in the contents of the POST.

The client will receive a response to this request. If successful, a 200 OK response will be received and the access token will be returned in a JSON structure. A refresh token will NOT be returned to the client.

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

{
  "access_token":"zzz...yyy",
  "token_type":"Bearer",
  "expires_in":14400
}