Hear from Salesforce leaders on how to create and deploy Agentforce agents.
Register now
Contact Us 1-800-596-4880
  1. Homepage
  2. API Manager
  3. About Using Policies
  4. About Provided Policies
  5. About OAuth 2.0

  6. About OAuth Grant Types

About OAuth Grant Types

OAuth provides the following grant types that the client can use to validate itself when it requests for a token.

  • AUTHORIZATION_CODE (default)

  • IMPLICIT

  • RESOURCE_OWNER_PASSWORD_CREDENTIALS

  • CLIENT_CREDENTIALS

Each requires a specific configuration of the OAuth Provider Global Element.

Authorization Code

The Authorization Code grant type is the most frequently used grant type and the most secure.

To implement an authorization code, your client needs to define the following information:

  • Client ID

  • Client Secret

  • Redirect URL

The following typical configuration of an oauth2 module includes an authorization code client:

<oauth2-provider:config
        name="oauth2Provider"
        providerName="SampleAPI"
        supportedGrantTypes="AUTHORIZATION_CODE"
        port="8081"
        authorizationEndpointPath="sampleapi/api/authorize"
        accessTokenEndpointPath="sampleapi/api/token"
        resourceOwnerSecurityProvider-ref="resourceOwnerSecurityProvider"
        scopes="READ_RESOURCE POST_RESOURCE" doc:name="OAuth provider module">
            <oauth2-provider:clients>
                <oauth2-provider:client clientId="myclientid" secret="myclientsecret"
                                        type="CONFIDENTIAL" clientName="Mule Bookstore" description="Mule-powered On-line Bookstore">
                    <oauth2-provider:redirect-uris>
                        <oauth2-provider:redirect-uri>http://localhost*</oauth2-provider:redirect-uri>
                    </oauth2-provider:redirect-uris>
                    <oauth2-provider:authorized-grant-types>
                        <oauth2-provider:authorized-grant-type>AUTHORIZATION_CODE</oauth2-provider:authorized-grant-type>
                    </oauth2-provider:authorized-grant-types>
                    <oauth2-provider:scopes>
                        <oauth2-provider:scope>READ_RESOURCE</oauth2-provider:scope>
                        <oauth2-provider:scope>POST_RESOURCE</oauth2-provider:scope>
                    </oauth2-provider:scopes>
                </oauth2-provider:client>
            </oauth2-provider:clients>
    </oauth2-provider:config>
xml

To test this example, perform an OAuth2 dance as follows:

  1. Invoke the authorization endpoint with a request that includes the client ID, the type of authorization you want to perform, the redirect URL, and the scopes you want to authorize:

    http://localhost:8081/sampleapi/api/authorize?response_type=code&client_id=myclientid&scope=READ_RESOURCE&redirect_uri=http://localhost:8081/redirect
    text

    The login page appears in the browser. After the user logs in, the provider sends a redirect to the redirect_uri. This redirect includes additional properties, including an access code.

  2. Send the access code to the token endpoint in a request that also includes the client ID, the client secret and some of the information in the previous call:

    http://localhost:8081/sampleapi/api/token?grant_type=authorization_code&client_id=myclientid&client_secret=myclientsecret&code=<use here the access code>&redirect_uri=http://localhost:8081/redirect
    text

    The JSON response appears:

    {
    "scope":"READ_RESOURCE",
    "expires_in":86400,
    "token_type":"bearer",
    "access_token":"huig0RVoGdFoz_mvBaV4ovfjj0Afe8yOAp_v2q0tunevsJVpD2HNRhx8lL6JnMDys7KE3O4TfijknWPzGJZ-NA"
}
    text

  3. Include the access_token as a header in your requests to access to protected resources:

    access_token=huig0RVoGdFoz_mvBaV4ovfjj0Afe8yOAp_v2q0tunevsJVpD2HNRhx8lL6JnMDys7KE3O4TfijknWPzGJZ-NA
    text

Implicit

The implicit grant type is not as secure as, but easier to use than the authorization code grant type. Javascript clients and mobile applications often use this grant type. The authorization server issues an access token directly and skips the step of issuing an intermediate access code.

The following typical configuration of an OAuth2 module includes an implicit grant client:

<oauth2-provider:config
        name="oauth2Provider"
        providerName="SampleAPI"
        supportedGrantTypes="IMPLICIT"
        port="8082"
        authorizationEndpointPath="sampleapi/api/authorize"
        accessTokenEndpointPath="sampleapi/api/token"
        resourceOwnerSecurityProvider-ref="resourceOwnerSecurityProvider"
        scopes="READ_RESOURCE POST_RESOURCE" doc:name="OAuth provider module">
            <oauth2-provider:clients>
                <oauth2-provider:client clientId="myclientid2" secret="myclientsecret"
                                        type="CONFIDENTIAL" clientName="Mule Bookstore" description="Mule-powered On-line Bookstore">
                    <oauth2-provider:redirect-uris>
                        <oauth2-provider:redirect-uri>http://localhost*</oauth2-provider:redirect-uri>
                    </oauth2-provider:redirect-uris>
                    <oauth2-provider:authorized-grant-types>
                        <oauth2-provider:authorized-grant-type>TOKEN</oauth2-provider:authorized-grant-type>
                    </oauth2-provider:authorized-grant-types>
                    <oauth2-provider:scopes>
                        <oauth2-provider:scope>READ_RESOURCE</oauth2-provider:scope>
                        <oauth2-provider:scope>POST_RESOURCE</oauth2-provider:scope>
                    </oauth2-provider:scopes>
                </oauth2-provider:client>
            </oauth2-provider:clients>
    </oauth2-provider:config>
xml

The following Mule flow that includes this configuration:

To test this example, perform an OAuth2 dance as follows:

  1. Invoke the authorization endpoint with a request that includes the client ID, the type of authorization you want to perform, the redirect URL, and the scopes you want to authorize. The structure of the request should look like the URI below:

    http://localhost:8082/sampleapi/api/authorize?response_type=token&client_id=myclientid2&scope=READ_RESOURCE&redirect_uri=http://localhost:8082/redirect
    text

  2. This displays the login page in the browser. After the user logs in, the provider sends a redirect to the redirect_uri. This redirect already includes the token, not just an access code:

    http://localhost:8082/redirect#access_token=d8gI_X7TLuAmYuZvlt0wx7sq1tnNgI9Ku9DazKAJYWXbB9QNzSTNxnXCeg75x5zZzT4zAcuCVkit6oBHkoSFow&token_type=bearer&expires_in=86399&scope=READ_RESOURCE
    text

  3. Include the access_token as a header in your requests to access to protected resources:

    access_token=huig0RVoGdFoz_mvBaV4ovfjj0Afe8yOAp_v2q0tunevsJVpD2HNRhx8lL6JnMDys7KE3O4TfijknWPzGJZ-NA
    text

Resource Owner and Password Credentials

The resource owner password credentials grant type is less secure than both the implicit and the authorization code grant types. The client needs to handle the user’s credentials. This requires that users have a high degree of trust in the client. This grant type is often used when the consumer of the protected resource is a widget of the same service.

The following code shows the typical configuration of an OAuth2 module includes resource owner password credentials:

<oauth2-provider:config
        name="oauth2Provider"
        providerName="SampleAPI"
        supportedGrantTypes="RESOURCE_OWNER_PASSWORD_CREDENTIALS"
        port="8083"
        authorizationEndpointPath="sampleapi/api/authorize"
        accessTokenEndpointPath="sampleapi/api/token"
        resourceOwnerSecurityProvider-ref="resourceOwnerSecurityProvider"
        scopes="READ_RESOURCE POST_RESOURCE" doc:name="OAuth provider module">
            <oauth2-provider:clients>
                <oauth2-provider:client clientId="myclientid3" secret="myclientsecret"
                                        type="CONFIDENTIAL" clientName="Mule Bookstore" description="Mule-powered On-line Bookstore">
                    <oauth2-provider:redirect-uris>
                        <oauth2-provider:redirect-uri>http://localhost*</oauth2-provider:redirect-uri>
                    </oauth2-provider:redirect-uris>
                    <oauth2-provider:authorized-grant-types>
                        <oauth2-provider:authorized-grant-type>PASSWORD</oauth2-provider:authorized-grant-type>
                    </oauth2-provider:authorized-grant-types>
                    <oauth2-provider:scopes>
                        <oauth2-provider:scope>READ_RESOURCE</oauth2-provider:scope>
                        <oauth2-provider:scope>POST_RESOURCE</oauth2-provider:scope>
                    </oauth2-provider:scopes>
                </oauth2-provider:client>
            </oauth2-provider:clients>
    </oauth2-provider:config>
xml

The following Mule flow includes this configuration:

To test this example:

  1. Send a POST request to the token endpoint that includes the user name and password:

    POST /sampleapi/api/token HTTP/1.1
Host: localhost:8083
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=john&password=doe&client_id=myclientid3&client_secret=myclientsecret&scope=READ_RESOURCE
    text

  2. If everything works correctly, a JSON response appears. For example:

    {
    "scope": "READ_RESOURCE",
    "expires_in": 86399,
    "token_type": "bearer",
    "access_token": "sgFJ8Y3VPcMOdldrFtCMcWe8VQLdOA8L6pcrqjTYA6L3G9bTIDiOFkiiSC2lmFx-RUKtkzTupW0ugU49hqHhpg"
}
    text

  3. You can now include the access_token as a header in your requests to access to protected resources:

    access_token=sgFJ8Y3VPcMOdldrFtCMcWe8VQLdOA8L6pcrqjTYA6L3G9bTIDiOFkiiSC2lmFx-RUKtkzTupW0ugU49hqHhpg
    text

Client Credentials

The client credentials grant type is the least secure grant type. Use this grant type when the client is the resource owner or an authorization has previously been arranged with the authorization server. In this grant type, an access token is obtained if the client identifier and the client secret are valid.

The following typical configuration of an OAuth2 module includes client credentials:

<oauth2-provider:config
        name="oauth2Provider"
        providerName="SampleAPI"
        supportedGrantTypes="CLIENT_CREDENTIALS"
        port="8084"
        authorizationEndpointPath="sampleapi/api/authorize"
        accessTokenEndpointPath="sampleapi/api/token"
        resourceOwnerSecurityProvider-ref="resourceOwnerSecurityProvider"
        scopes="READ_RESOURCE POST_RESOURCE" doc:name="OAuth provider module">
            <oauth2-provider:clients>
                <oauth2-provider:client clientId="myclientid4" secret="myclientsecret"
                                        type="CONFIDENTIAL" clientName="Mule Bookstore" description="Mule-powered On-line Bookstore">
                    <oauth2-provider:redirect-uris>
                        <oauth2-provider:redirect-uri>http://localhost*</oauth2-provider:redirect-uri>
                    </oauth2-provider:redirect-uris>
                    <oauth2-provider:authorized-grant-types>
                        <oauth2-provider:authorized-grant-type>CLIENT_CREDENTIALS</oauth2-provider:authorized-grant-type>
                    </oauth2-provider:authorized-grant-types>
                    <oauth2-provider:scopes>
                        <oauth2-provider:scope>READ_RESOURCE</oauth2-provider:scope>
                        <oauth2-provider:scope>POST_RESOURCE</oauth2-provider:scope>
                    </oauth2-provider:scopes>
                </oauth2-provider:client>
            </oauth2-provider:clients>
    </oauth2-provider:config>
xml

The following Mule flow includes this configuration:

To test this example:

  1. Send a POST request to the token endpoint that includes the user name and password:

    POST /sampleapi/api/token HTTP/1.1
Host: localhost:8082
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=myclientid4&client_secret=myclientsecret&scope=READ_RESOURCE
    text

  2. If everything works correctly, a JSON response appears. For example:

    {
    "scope": "READ_RESOURCE",
    "expires_in": 86400,
    "token_type": "bearer",
    "access_token": "4juchYVW5ZNNSH_OOU0jxziixjdJ7yhdZTJW5tbi80cJO3oAF-lTD6D05gw2EKA9yxUuOLf-f_oVBX6z0aRI9w"
}
    text

  3. Include the access_token as a header in your requests to access protected resources:

    access_token=4juchYVW5ZNNSH_OOU0jxziixjdJ7yhdZTJW5tbi80cJO3oAF-lTD6D05gw2EKA9yxUuOLf-f_oVBX6z0aRI9w