Authenticate using OAuth 2.0

OAuth 2.0 enables the safe retrieval of secure resources while protecting user credentials. Some apps may need to authenticate during the configuration phase and others may need OAuth only when a user invokes a service.

In general, OAuth authentication follows a six step pattern:

  1. An application requests authorization on a user's behalf.
  2. The application obtains a Grant Token.
  3. The client requests an access token by using the Grant Token.
  4. The authorization server validates the Grant Token and issues an Access Token and a Refresh Token.
  5. The client requests the protected resource, authenticating using the Access Token.
  6. The resource server verifies the Access Token and serves the request.

Learn more about the OAuth 2.0 Specifications.

Eloqua OAuth 2.0 endpoints:

Authorization endpoint: https://login.eloqua.com/auth/oauth2/authorize

Token endpoint: https://login.eloqua.com/auth/oauth2/token


Note: The following examples assume that all requests are successful. For a detailed description of possible request responses, including a variety of failure types, see: the OAuth Reference.

To authenticate using OAuth 2.0

Eloqua supports three possible flows that an application can use to obtain access on behalf of a resource owner: Authorization Code grant, Implicit grant, Resource Owner Password Credentials grant. In general, you should use the Authorization Code grant for Apps that extend Eloqua's functionality.

Important: Before you begin, you need a unique Client ID and Client Secret for your app. In your Eloqua instance navigate to Settings > AppCloud Developer then select Create New App. Learn more about AppCloud app creation. Fill out the required information and enter your app's URL into the Callback Url field under the OAuth heading then click Save. You should then be presented with valid Client Id and Client Secret values.

To authenticate using an authorization code grant:

  1. Request initial authorization through the login.eloqua.com/auth/oauth2/authorize endpoint. A call to this endpoint will trigger a prompt for users to enter their credentials.

    /auth/oauth2/authorize has five possible URL parameters:

    ParameterValueRequired?
    response_typeMust be "code"Yes
    client_idYour app's Client Id provided when registering your app (see above)Yes
    redirect_uriYour app's registered redirection endpoint, should be the same URL you entered as the Callback Url when registering your app (see above)Yes
    scopeMust be “full” or not suppliedNo
    stateAn optional value that has meaning for your AppNo

    The call to the authorize endpoint might resemble:

    https://login.eloqua.com/auth/oauth2/authorize?response_type=code
    &client_id=a1b2c3d4&redirect_uri=https://client.example.com/cb
    &scope=full&state=xyz

    Once users enter their credentials and accept your app's request to access Eloqua on their behalf, they are redirected to the redirect_uri with a Grant Token (which is in this case an Authorization Code) attached in the code URL parameter, as in the following example:

    HTTP/1.1 302 Found
    Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz

  2. Use the Grant Token to obtain an Access Token and Refresh Token using a POST request to the login.eloqua.com/auth/oauth2/token endpoint.

    The POST request should include a JSON body with the following parameters:

    Parameter Value Required?
    grant_type The name of the Grant Token's type. In this case: authorization_code Yes
    code The Grant Token Yes
    redirect_uri Your app's registered redirection endpoint Yes

    The following example call requests an Access Token and a Refresh Token token using the Grant Token obtained previously:

    POST https://login.eloqua.com/auth/oauth2/token
    Authorization: Basic Q09NUEFOWVhcdXNlcjE6cGFzc3dvcmQxMjM=
    {
    "grant_type":"authorization_code",
    "code":"SplxlOBeZQQYbYS6WxSbIA",
    "redirect_uri":"https://client.example.com/cb"
    }
    Note: This request must authenticate using HTTP basic. Use your app’s Client Id as the username and its Client Secret as the password. The format is client_id:client_secret. Encode the string with base-64 encoding, and you can pass it as an authentication header. The system does not support passing Client Id and Client Secret parameters in the JSON body, and, unlike basic authentication elsewhere, you should not include your site name. Learn more about basic authentication with Eloqua.

    The authorization server validates the authorization code and if valid responds with a JSON body containing the Access Token, Refresh Token, access token expiration time, and token type, as in the following example:

    HTTP/1.1 200 OK
    Content-Type: application/json
    {
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
    }
  3. Store and use the access and refresh tokens.

    When your app needs a protected resource, it authenticates during the request using the Access Token. The following call to Eloqua's application API uses the access token to authenticate:

    GET /resource/1 HTTP/1.1
    Host: api.eloqua.com
    Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

    api.eloqua.com verifies the Access Token, and supplies the requested resource if the access token is valid.

    Note:

    • Authorization Codes expire in 60 seconds (intended for immediate use)
    • Access Tokens expire in 8 hours
    • Refresh Tokens expire in 1 year
    • Refresh Tokens will expire immediately after being used to obtain new tokens, or after 1 year if they are not used to obtain new tokens

  4. If the access token has expired, you should send your Refresh Token to login.eloqua.com/auth/oauth2/token to obtain new tokens as in the following example:
    POST https://login.eloqua.com/auth/oauth2/token
    Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
    {
    "grant_type":"refresh_token",
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
    "scope":"full",
    "redirect_uri":"https://client.example.com/cb"
    }

    If the request is successful, the response is a JSON body containing a new access token, token type, access token expiration time, and new refresh token:

    HTTP/1.1 200 OK 
    Content-Type: application/json
    {
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"MToxLUIyZHRNTUZsazIwNmZFTy1"
    }

    Store the new refresh token as the old refresh token is no longer valid. Then proceed to make your call using the new access token.

To authenticate using an implicit grant:

An implicit grant is a browser-based authentication best used for in-browser applications and instead of issuing an authorization code that is exchanged for an access token, Eloqua issues an access token directly.

Warning: An authorization code grant is recommended in the vast majority of cases as it has fewer potentially negative security implications.
  1. Request an access token through a GET request to the login.eloqua.com/auth/oauth2/authorize endpoint using the following URL parameters:
    ParameterValueRequired?
    response_typeMust be "token"Yes
    client_idYour app's Client Id provided when registering your app (see above)Yes
    redirect_uriYour app's registered redirection endpoint, should be the same URL you entered as the Callback Url when registering your app (see above)Yes
    scopeMust be “full” or not suppliedNo
    stateAn optional value that has meaning for your AppNo

    The call to the authorize endpoint might resemble:

    https://login.eloqua.com/auth/oauth2/authorize?response_type=token
    &client_id=s6BhdRkqt3&redirect_uri=https://client.example.com/app
    &scope=full&state=xyz

    Once users enter their credentials and accept your app's request to access Eloqua on their behalf, they are redirected to the redirect_uri with an authorization code attached in the access_token URL parameter, as in the following example:

    HTTP/1.1 302 Found
    Location: https://client.example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA
    &token_type=bearer&expires_in=28800&state=xyz
  2. Use the access token to request resources on the user's behalf.

To authenticate using a resource owner password credentials grant

With the resource owner password credential grant, the App provides the resource owner's username and password to the authorization server in order to obtain an access token. This grant type is ideal when an app already has the necessary Eloqua user names and passwords stored, and wants to use access tokens for added security.

  1. Obtain an Access Token and a Refresh Token by making a POST request to the login.eloqua.com/auth/oauth2/token endpoint using a JSON body containing the following parameters:
    ParameterValueRequired?
    grant_typeMust be "password"Yes
    scopeMust be "full" or not suppliedNo
    usernameThe user's site name and username in the form sitename + '/' + usernameYes
    passwordThe user's passwordYes

    Note: This request must authenticate using HTTP basic. Use your app’s Client Id as the username and its Client Secret as the password. The format is client_id:client_secret. Encode the string with base-64 encoding, and you can pass it as an authentication header. The system does not support passing Client Id and Client Secret parameters in the JSON body, and, unlike basic authentication elsewhere, you should not include your site name. Learn more about basic authentication with Eloqua.

    The call to the token endpoint might resemble:

    POST https://login.eloqua.com/auth/oauth2/token
    Authorization: Basic Q09NUEFOWVhcdXNlcjE6cGFzc3dvcmQxMjM=
    {
    "grant_type":"password",
    "scope":"full",
    "username":"testsite\\testuser",
    "password":"user123"
    }
  2. If the request is successful, the response is a JSON body containing an Access Token, a Refresh Token, the access token expiration time, and token type:
    HTTP/1.1 200 OK
    Content-Type: application/json
    {
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKW"
    }
  3. You can then use the Access Token and store the Refresh Token, using the Refresh Token as needed to renew the credentials. Follow steps 3 and 4 of "To authenticate using an authorization code grant" above for more information.

Related

Authentication

Authenticate using OAuth 2.0

Get started