OAuth Support
Configure an API with OAuth.
Table of Contents
- What is OAuth?
- What OAuth versions are supported?
- How do I configure my API with an OAuth Provider?
- What's the difference between an OAuth Provider and a Third-Party Provider?
- What grant types does OAuth support?
- How does OAuth 2-Legged and 3-Legged Authorization work?
- How are tokens generated and used in OAuth?
- What is a Refresh Token?
- What is an access token?
- What is a Grant Property?
- How does Resource Owner Authentication Page Login Branding work?
- What is an Authorization Server and how does it work?
- What are the OAuth 2.0 Endpoints and how do they work?
- What are the OAuth 1.0a Endpoints?
- What is an Authorization Server Client Authentication Policy?
- How does Scope Mapping work?
- How does the proxy API send OAuth-related information to my API?
What is OAuth?
OAuth is an open standard security protocol for authorization that allows you to share private resources stored on one site with another site without having to share credentials.
One advantage of OAuth is that it supports both authentication and authorization in such a way that an application does not need to give access to the user's credentials. For example, in the platform you can sign in using your Facebook® credentials, or on the API Details page you can share an API to Facebook, Twitter, and LinkedIn. These elements of the platform are configured as private resources.
In addition, OAuth can potentially extend the userbase of your APIs and applications by providing a flexible, familiar way to access them. For example, if you have multiple APIs added to the platform repository, and each API has granted access to multiple apps, you then have a broadened developer community, in addition the substantial number of users that are using the applications.
Access permissions are initially established by supplying a Resource that is dictated by the application (for example, username/password, email address). For example, if you supply username and password tokens, each token grants access to a specific site for a specific resource for a defined duration. This allows you to grant a third party site access to their information stored with another service provider, without sharing their access permissions or the full extent of their data.
OAuth 2.0 defines the following roles of users and applications:
- Resource Owner—The resource owner is the person or application that owns the data that is to be shared. For example, a user on Facebook could be a resource owner. The resource they own is their data. The resource owner is typically a person, but could also be an application.
- Resource Server—The resource server is the server hosting the resource owner's data. For example, Facebook is a resource server.
- Client Application—The client application is the application requesting access to the resources stored on the resource server. The resources, which are owned by the resource owner. A client application could be a game requesting access to a user's Facebook account.
- Authorization Server—The OAuth authorization server is the OAuth service provider's server, which authorizes the client app to access the resources of the resource owner. The authorization server and the resource server might be the same server, but might be different.
OAuth in the context of an API in the platform includes the following:
- Client Application—The application that wants to access the resource owner's data, which the API can provide access to. For example, the client application directs the user to the OAuth Provider with a request for the user to authorize access to resource information. The user must authenticate with credentials (for example, username/password).
- OAuth Provider—An application that keeps track of which user has given authorization to which application and has the ability to issue tokens to represent authorizations. A single OAuth Provider can support multiple APIs.
- Resource Owner—User of an API and application.
- Resource—User's credentials (i.e., username / password, email address, etc.)
- API—Works closely with OAuth Provider to trust tokens issued by the provider to let the client application access the resource owner's resource held at the API.
What OAuth versions are supported?
The platform supports the 1.0a and 2.0 versions of OAuth.
How do I configure my API with an OAuth Provider?
If your API currently supports OAuth it must be associated with an OAuth Provider configuration that represents the OAuth use case that is most appropriate for the intended usage of the API, and resource mapping must be configured for selected operations to establish authorization permissions. This is accomplished using the OAuth Details function on the API Details page.
Process:
A. API Administrator Installs OAuth Provider Features
After an API Administrator adds an API, they then define one or more OAuth Provider configurations:
- Each configuration is predefined with authentication domain, supported grant and access token types, and resources definitions / permissions (i.e., API operations that applications can map too and can get authorization from).
- The number of OAuth Provider configurations defined is based on the OAuth use cases that the API supports.
- These definitions are available for selection in the "OAuth Provider" drop-down of the API OAuth Wizard.
B. Launch OAuth Details Wizard and Select OAuth Provider
The first step is to select an OAuth Provider for both the Production and Sandbox endpoints of your API.
- On the API > Details page, click OAuth Details. The API OAuth Wizard launches and the Provider page displays.
- Based on your API configuration you will have one or more Production or Sandbox endpoints. In the OAuth Provider section select a provider name for each endpoint you would like to configure.
- If you are configuring a Proxy API, select a pre-defined OAuth Provider.
- If you are configuring the Target API, select 3rd Party Provider.
- After selecting a provider the wizard updates to reflect the elements that comprise the provider definition.
C. Specify Authorization Details
Based on the OAuth version supported for the provider selected, specify the details for 1.0a or 2.0 OAuth Versions. If you select OAuth 2.0, the OAuth Options section displays where you can configure Authorization Grant Types.
Note: When specifying an Authorization Server URL in the platform, it's important to verify that the client application is authorized to use the grant type that the OAuth Provider is configured to support.
- Select an OAuth version. Version 2.0 and 1.0a are supported.
- Specify the required endpoint URLs for each OAuth version
- If you selected OAuth 2.0, select an Authorization Grant Type and Authorization Server Client Authentication Policy.
D. Configure Scope Mapping
If you selected a predefined OAuth Provider, the resources (i.e., operations) of the current API have already been defined and authorized for use. On the Scope Mapping page, you identify which the operations your applications will need to get authorization for and the scope.
For example, Application1 includes a calendar and may need access to the API's calendar operation, and Application2 includes an email client and may require access to the API's address operation.
- Click the radio button of the Scope Mapping approach you would like to use. API-wide Mapping or Operation Specific Mapping.
- In the Scope column, click Select. The Select Scope popup displays. Click the checkbox of the operations you would like to include in the scope of the current API. Deselect the checkboxes of operations you do not want to include in the configuration.
- After completing your configuration, click Save.
What's the difference between an OAuth Provider and a Third-Party Provider?
An Identity Provider is a central OAuth-enabled provider that provides both user authentication and user authorization. Using the API OAuth function, you can select a pre-defined OAuth Provider or a third-party provider:
- OAuth Provider—If you select a pre-defined OAuth Provider the configuration will be applied to the Proxy API only. Pre-defined providers are filtered to contain OAuth versions, grants, policies, and resource mapping information that relate to specific OAuth use cases. Tokens issued by this OAuth Provider could be validated by all agents from Akana.
Note: OAuth providers are set up by the Site Admin in Administration / Domains / OAuth Provider. If the OAuth provider you need is not on the drop-down list, contact your Site Admin. - 3rd Party Provider—Choose this option if the physical endpoint will be authorizing the OAuth requests. The app still needs to send the OAuth token as part of the request, but the platform passes the token through to the physical endpoint. This allows us to support the API in the Test Client so that apps can test against it. Provide all the information needed based on OAuth version and security configuration a specific API supports.
Reference: API > API Details > OAuth Details > OAuth Provider
What grant types does OAuth support?
Access or permission to use a resource by an OAuth Provider is facilitated using grants.
Note: The platform supports all four grant types for OAuth 2.0, and Authentication Code only for OAuth 1.0a.
OAuth defines the following grant types that reflect different authorization mechanisms:
2-Legged
The following grant types are used in the 2-Legged OAuth scenario.
| Grant Type | Description |
|---|---|
| Client Credentials | The client presents its own credentials to the OAuth Authorization Server in order to obtain an access token. This access token is either associated with the client’s own resources, and not a particular resource owner, or is associated with a resource owner for whom the client is otherwise authorized to act. |
| Resource Owner Password Credentials | The client collects the resource owner’s password and exchanges it at the OAuth AS for an access token, and often a refresh token (see below). This grant type is suitable in cases where the RO has a trust relationship with the client, such as its computer operation system or a highly privileged application since the client must discard the password after using it to obtain the access token. |
3-Legged
The following grant types are used in the 3-Legged OAuth scenario.
| Grant Type | Description |
|---|---|
| Authorization Code | An authorization code is returned to the client through a browser redirect after the resource owner gives consent to the OAuth Authorization Server. The client then exchanges the authorization code for an access token. Resource owner credentials are never exposed to the client. |
| Implicit | An access token is returned to the client through a browser redirect in response to the resource owner authorization request. This grant type is suitable for clients that do not support keeping client credentials confidential (for use in authenticating with the OAuth Authentication Server) such as client applications implemented in a browser using a scripting language like JavaScript. |
Reference: Site Administrator > Domains > Configure OAuth Provider > Grant Types > 3-Legged / 2-Legged Grant Types
How does OAuth 2-Legged and 3-Legged Authorization Work?
The number of legs used to describe an OAuth request typically refers to the number of parties involved. Legs generally mean that access is shared by the client with other clients.
- In the simple OAuth flow (a client, a server, and a resource owner), the flow is described as 3-Legged.
- When the client is also the resource owner (i.e., acting on behalf of itself), it is described as 2-Legged.
This section provides a brief description of 3-Legged versus 2-Legged OAuth:
3-Legged:
In 3-Legged OAuth a resource owner wants to give a client access to a server without sharing their credentials (i.e. username/password). For example, a user (resource owner) wants to give a third-party application (client) access to his Twitter account (server).
This scenario works as follows:
- Client signs up to the server and obtains client credentials (i.e., consumer key and secret).
- User wants to give the client access to his protected resources on the server.
- Client retrieves the temporary credentials (i.e., request token) from the server.
- Client redirects the resource owner to the server.
- Resource owner grants the client access to his protected resources on the server.
- Server redirects the user back to the client.
- Client uses the temporary credentials to retrieve the token credentials (i.e., access token) from the server.
- Client uses the token credentials to access the protected resources on the server.
2-Legged:
2-Legged OAuth describes a typical client-server scenario without any user involvement. For example, a local Twitter client application accessing your Twitter account.
This 2-legged OAuth scenario consists of the first and last steps of 3-legged OAuth:
- Client has signed up to the server and got his client credentials (i.e., consumer key and secret).
- Client uses his client credentials (and empty token credentials) to access the protected resources on the server.
Reference: Site Administrator > Domains > Configure OAuth Provider > Grant Types > 3-Legged / 2-Legged Grant Types
How are tokens generated and used in OAuth?
OAuth tokens are generated by the platform. When a Site Administrator or API Provider defines an OAuth Provider, they select the supported OAuth grant types, whether the authorization server supports Refresh Tokens, and what type of access token is supported. The type of token issued is based on the configuration of the OAuth Provider that is assigned to the API.
- Tokens are used so that an app's private credentials do not have to be shared with an API.
- Instead of OAuth sending the password, it provides a token so the API does not need to see the app password.
- OAuth validates the user, not the app. The API can see the user's password, but the app cannot.
See What is an access token? for details on access token support for OAuth 2.0 and OAuth 1.0a.
What is a Refresh Token?
Refresh Tokens are credentials used to obtain access token:
- They are issued as a string and represent the authorization granted to the client by the resource owner.
- The token denotes an identifier used to retrieve the authorization information.
- They are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope.
- Issuing a refresh token is optional at the discretion of the authorization server. If the authorization server issues a refresh token, it is included when issuing an access token.
- Unlike access tokens, refresh tokens are intended for use only with authorization servers and are never sent to resource servers.
Reference: Site Administrator > Domains > Configure OAuth Provider > Grant Types > Issue Refresh Tokens
What is an access token?
An access token is issued as a string that represents an access authorization issued to the client. It is used by the client to access protected resources hosted by the resource server. Access tokens are issued to clients by an authorization server with the approval of the resource owner. Each access token includes an expiration attribute that indicates how long the token is valid.
Note: An access token timeout is typically 15 days (or 1296000 seconds).
OAuth 2.0:
There are two types of access tokens:
- Bearer Token—This access token type is a security token with the property that any party in possession of the token (a "bearer") can use the token in any way that any other party in possession of it can. Using a bearer token does not require a bearer to prove possession of cryptographic key material (proof-of-possession).
- Message Authentication Code (MAC)—This access token type is a security code that is typed in by the user of a computer to access accounts or portals. This code is attached to the message or request sent by the user. Message Authentication Codes (MACs) attached to the message must be recognized by the receiving system in order to grant the user access. MACs are commonly used in electronic funds transfers (EFTs) to maintain information integrity.
As part of the OAuth Provider Domain configuration process, the Add Domain Wizard requires that you select what kind of token should be issued (Bearer or Mac).
OAuth 1.0a:
A token shared secret is issued one time only.
Reference: Site Administrator > Domains > Configure OAuth Provider > Grant Types > Access Token Type
What is a Grant Property?
A grant property is a custom property that a resource owner can define in the client application to provide additional information per API on whether to apply restrictions/constraints to the grant or add additional services at the scope of the grant. It allows you configure how an app will use the permissions you are giving it (for example, in a banking app only provide transaction details or current balance, but do not allow a withdrawal).
Grant properties are initially defined in the client application and assigned a "tag." The Site Administrator or API Provider can then reference the grant properties in the OAuth Provider domain by specifying a Property ID (which represents the Tag of the property definition) and Property Label (which is a description label that is internal to the platform).
After you have successfully logged into your application via the login screen associated with the OAuth Provider the API, an app authorization screen displays that typically includes some type of authorize option and can optionally include fields for entering any custom grant properties data. Here you enter the values for the grant properties, and click Authorize (or equivalent option). A token is given to the application and an authorization successful message is returned. The application can then use this token to start sending requests. The grant properties are then sent back to the client application for validation.
Example (Using Grant Property to Apply Restriction):
- If the API being secured is a money transfer API, the resource owner might want a restriction to limit the maximum value of a transaction to $100, with a maximum of only one transaction per month (for example, magazine subscription application).
- To support this, the provider could define a "Maximum transaction amount" property, and a “Maximum number of transactions per month property in the application, and specify the Property ID (i.e., tag) in the OAuth Provider domain definition on the Grant Property page.
- The grant property labels display with text entry fields on the application app authorization screen after the login is successful. Enter the values for the grant properties and click Authorize.
Reference: Site Administrator > Domains > Configure OAuth Provider > Properties
How does Resource Owner Authentication Page Login Branding work?
When a user logs into your application using the OAuth Provider configuration, they must see a Resource Owner Authentication page (login screen) that is custom branded to your organization. The Branding page of the OAuth Provider domain is used to configure this page. Two branding options are offered:
- Integrate with Existing Identity Provider—You can link to a Resource Owner Authentication page provided directly by an identity provider such as Facebook or Google. This is accomplished by specifying the Authorization Server URL on the Branding page of the OAuth Provider domain configuration.
- Integrate with Platform Identity Provider—The platform allows you to integrate with backend identity systems and configure a custom Resource Owner Authentication page. You can customize the login with a unique logo that represents your organization, footer text (for example, copyright information), and the URL you want to offer to Resource Owners and applications to access this OAuth provider capabilities.
Reference: Site Administrator > Domains > Configure OAuth Provider > Branding
For more information on the settings on the OAuth Provider domain branding page, see What are the settings on the OAuth Provider Branding page and what options should I choose?
What is an Authorization Server and how does it work?
An authentication server is an application that facilitates authentication of an entity that attempts to access a network. Such an entity may be a human user or another server. An authentication server can reside in a dedicated computer, an Ethernet switch, an access point or a network access server.
Authentication Servers can be set up in a variety of ways, depending upon the security scheme of the network they are serving. The basic process for authenticating a user includes the following steps:
- A user dials into a network through a communications server, or Network Access Server.
- The Network Access Server forwards the user identification and password to the Authentication Server.
- Then the Authentication Server validates the user and provides access privileges to the network.
What are the OAuth 2.0 Endpoints and how do they work?
OAuth 2.0 defines an Authorization, Token, and Redirection endpoints. They are typically a URI on a web server.
API Administrators who are defining OAuth Providers using the Add OAuth Wizard (via Site Administration > Domains) or are configuring OAuth for a specific API using the API OAuth Wizard (via API > Details) will specify an Authorization URL, Token Endpoint URL, and Redirection URL if they are using OAuth 2.0.
This section provides a brief overview of how an Authorization Server works in respect to each endpoint:
OAuth 2.0 Endpoints:
- Authorization Endpoint is the endpoint on the authorization server where the resource owner provides credentials, such as username and password, in and grants authorization to the client app to access the resources or a specified subset of the resources.
- Token Endpoint is the endpoint on the authorization server where the client application exchanges the authorization code, client ID, and client secret and receives in exchange an access token which allows the app to access the approved resources.
- Redirection Endpoint is the endpoint in the client application where the resource owner is redirected to, after having granted authorization at the authorization endpoint.
Authorization Server Workflow:
- When a client application wants access to the resources of a resource owner, hosted on a resource server, the client application must first obtain an authorization grant.
- Before a client application can request access to resources on a resource server, the client application must first register with the authorization server associated with the resource server. After the registration is complete, the registration remains valid, unless the client app registration is revoked.
- At registration the client application is assigned a client ID and a client secret (password) by the authorization server. The client ID and secret is unique to the client application on that authorization server. If a client application registers with multiple authorization servers (for example, Facebook, Twitter, or Google), each authorization server will issue its own unique client ID to the client application.
- Whenever the client application requests access to resources stored on that same resource server, the client application needs to authenticate itself by sending along the client ID and the client secret to the authorization server.
- During the registration the client also registers a redirect URI. This redirect URI is used when a resource owner grants authorization to the client application. When a resource owner has successfully authorized the client application via the authorization server, the resource owner is redirected back to the client application, to the redirect URI.
What are the OAuth 1.0a Endpoints?
OAuth 1.0a supports the following endpoints:
- Request Token Endpoint URL —A Request Token is used by the consumer to ask the user to authorize access to the protected resources. The Request Token Endpoint URL is used to obtain an unauthorized Request Token.
- User Authorization URL—The consumer cannot use the Request Token until it has been authorized by the user. The User Authorization URL is used to obtain user authorization for Consumer access.
- Access Token Endpoint URL—An access token is a value used by the consumer to gain access to the protected resources on behalf of the user, instead of using the user's service provider credentials. The Access Token Endpoint URL is used to exchange the user-authorized Request Token for an access token.
For more information on these endpoint types, refer to the OAuth Core 1.0, Revision A specification (http://oauth.net/core/1.0a/)
What is an Authorization Server Client Authentication Policy?
If you are using the Akana Network Director as the Authentication Server specified in your OAuth configuration, the platform provides a series of client authentication policies that can be used to authenticate the client's credentials:
- Basic Authentication—Basic authentication requires that users provide a valid user name and password to access content. All major browsers support this authentication method and it works across firewalls and proxy servers. The disadvantage of Basic authentication is that it transmits passwords across the network using weak encryption. You should use Basic authentication only when you know that the connection between the client and the server is secure.
- HTTPs 2-Way Authentication—Two-way authentication requires that both the client and server authenticate each other with certificates.
- Form-Based Authentication—Form-based authentication mode lets you manage client registration and authentication at the application level, instead of relying on the authentication mechanisms provided by the operating system. It works well for sites or applications on public web servers that receive many requests.
How does Scope Mapping work?
Operations in an API act on data objects called scopes. Scopes are permissions that OAuth can read to get access to specified operations from one site to another. The platform uses grant resources for authorization of an API. The authorization could be fine-grained (at the object level), or could be for additional services.
Although the approach for organizing API Scopes varies from API to API, the scopes are typically organized as follows:
- Scopes are grouped in a catalog in organized into a "Scope Hierarchy" similar to the diagram below.
- The scope represents a catalog of folders and services published on the host.
- The root node is the initial entry point to the host.
- Each scope in the catalog includes a "Scope URL" as well as the root node.
- Each scope can also be referenced by a symbol {id} that represents the integer ID of the resource.
Scopes are defined in a hierarchy of permissions that represent the list of actions to be performed. For example, if you have a credit card service API, you may have scopes like Charge Account, Deposit, Cash Advance, or Get Statement, in addition to account management services like Add Card, Report Fraud Transaction, etc. Scopes are generally added to the hierarchy based on a logical sequence. For example, if your credit card service API has the ability to deposit, you might make Deposit a sub-scope under Withdraw.
A base set of scopes are initially defined in the OAuth Provider domain and the API provider can perform additional filtering when on the scope list when configuring the API OAuth Wizard. These scopes map to operations that are defined in one more APIs that the OAuth Provider domain will be serving.
The API OAuth Wizard accessible via the API Details page, includes a Scope Mapping section that allows you to specify a Scope for selected operations, or enable API-wide Mapping. For Operation-specific Mapping you specify the Scope URL or symbol {id}, for API-wide Mapping you specify the Scope URL of the Root Node.
Example (Using Grant Scope to Provide an Additional Service):
The following example illustrates a walkthrough of configuring scopes starting with the API definition, continuing with the OAuth Provider, and finally attaching the OAuth Provider to the API and performing the scope mapping:
- An API includes a transaction using a defined OAuth grant requesting that a notification be issued using an Email delivery method when an application makes a "charge."
- To support this, the API Provider must include a "Profile" and "Email" operation in the API definition, and must also select application and OAuth security policies, plus a monitoring policy. The following illustration shows the Operation and Policy sections of the Proxy page in the Add a New API Wizard.
- The API Provider or Site Administrator must configure the "Profile" and "Email" resource hierarchy in the OAuth Provider definition. The following illustration shows how the Scopes page of the Add Domain Wizard for an OAuth Provider could be configured for this example:
- On the API Details page, the API Provider must then select OAuth Details and configure the resources on the Scope Mapping page, select the OAuth provider, and select Operation-specific mapping and configure the "Profile" and "Email" resources by selecting the checkbox of the resource from the hierarchy. The following illustration shows the two resources configured in the API OAuth Wizard:
- After the scopes are properly configured, when a charge is made to the application, the grant scope will be invoked and the API will issue an email with information about the charge.
How does the proxy API send OAuth-related information to my API?
When you set up your API on the platform, using the platform as a proxy, your API is the Target API and the platform is the Proxy API.
When an app sends a request to the proxy API, if the API is using the platform as a proxy API and is using the OAuth policy, custom headers are added in the outbound request from the proxy API, which is the target API's inbound message. These outbound request headers include key information such as:
- Resource owner identity
- Grant properties
- Possibly, other information about the grant
It's important for API developers to know about these properties so that they can implement the API to work with any authorization restrictions (grant properties) set up by the resource owner for the application under the grant.
For example, the API developer could use the headers to validate that the proxy has authenticated the user, and to get the UserID of the consumer (end user) making the call.
An example of what these custom headers might look like, in the inbound message to the target API, is shown below.
OAuth_ClientID: acmepayments-7zQLGrDd2163LSKqOOkJ2QAf OAuth_Scope: Wall OAuth_Properties: Prop1=Prop1Value OAuth_TokenType: MAC OAuth_version: 2.0 OAuth_ResourceOwnerDomain: MyOpenIDConnectProvider OAuth_ResourceOwnerUserInfo: first_name=Jane,title=Ms,sub=jmead,$EMAIL="[email protected]", $LASTNAME=Mead,email="[email protected]",family_name=Mead,mobile=99999999999 OAuth_ResourceOwnerUID: https://www.google.com/accounts/o8/id?id=AItOawkXDyU8_9K2CEYmXxhZshHC080Eq7FIHXY OAuth_Signature_Method: HMACSHA256
For details about the headers, what they mean, and valid values, see the table below.
| Header | Description/Values |
|---|---|
| OAuth_ClientID | The OAuth client ID for the client sending the request. |
| OAuth_Scope | One or more specific scopes assigned to the grant; these are scopes that the resource owner is granting access to. Scopes are defined by the resource server and approved by the resource owner. Separate multiple scopes by spaces. Example: Wall Calendar |
| OAuth_Properties | Name/value pairs for OAuth grant properties that the end-user has selected. Multiple grant properties are separated by commas. |
| OAuth_TokenType | The OAuth token type: MAC or Bearer. |
| OAuth_version | The OAuth version being used: 1.0a or 2.0. |
| OAuth_ResourceOwnerDomain | The domain that the OAuth resource owner belongs to. This domain is selected as the Resource Owner (End User) domain when configuring the OAuth Provider in the platform. |
| OAuth_ResourceOwnerUserInfo | Details of the Resource Owner User Attributes. |
| OAuth_ResourceOwnerUID | The resource owner's unique ID, given by the resource owner domain. |
| OAuth_Signature_Method | The signature method used in the request message for signing the oauth token, indicating the strength of the security used in the request message. This applies only for OAuth 1.0a tokens and OAuth 2.0 MAC token. Example: HMACSHA256. We support the following OAuth signature methods:
|