App OAuth Profile
Specify OAuth settings that you want to support/use for your app.
Table of Contents
- How do I set up my app to use OAuth?
- What is the OAuth Profile and what choices should I make?
- How do I configure my app's OAuth profile settings?
- What are the settings available on the App OAuth Profile page?
- How do I configure OAuth credentials?
- How do I configure a Resource Owner OAuth Authorization page for my app?
- What are the OAuth 2.0 Client Types?
How do I set up my app to use OAuth?
If you want your app to support OAuth, you'll need to:
- Decide which service you want to use for user authentication (for example, Google, Facebook) and set up an account for yourself so you have credentials.
- Code your app to send, receive, and validate OAuth messages, including encryption and decryption if you want to use those.
- Specify the OAuth settings you prefer to use, as part of your app setup in the platform, via App Details > OAuth Profile.
What is the OAuth Profile and what choices should I make?
In the developer portal, your app's OAuth Profile allows you to specify settings and choices with regard to how the app uses OAuth.
For example:
- What authentication method do you want to use for the API to authenticate your app?
- Do you want to use encryption?
- If your app is using encryption, which encryption algorithm is it using?
- Do you have requirements about grant expiration?
- Do you want to display a different logo on your app's OAuth grant Authorization page, where your users approve your access request, or do you want to use the default logo set up for your app in the platform?
How do I configure my app's OAuth profile settings?
Once you've set up the basic information about your app (see How do I create a new app?), you can set up the values you want to use for your app's OAuth implementation.
To configure app OAuth profile settings:
- Log in to the developer portal.
- Go to the App Details page for your app, and click OAuth Profile.
- Change the settings as needed. For explanations of your choices, refer to the following tables:
- Branding: see Branding Settings.
- Access Token: see Access Token Settings.
- Authentication: see Authentication Settings.
- ID Token: see ID Token Settings.
Note: if you see any additional settings on this page, consult with the Site Admin if you have questions on the settings.
- When done, click Save.
What are the settings available on the App OAuth Profile page?
The App OAuth Profile page lets you configure values that your users will see on the OAuth Authorization page when authorizing your grant request. You can also configure your OAuth preferences and other values relating to OAuth support on this page. When you connect to an API, these preferences are used.
The tables below provide basic information about the settings available, the choices for each setting, and reasons why you might make specific choices. There are four groups of settings. If you see additional settings, check with your Site Admin for information on what choices to make. The groups are:
Branding Settings:
| Setting | Explanation / possible values |
|---|---|
| Logo | Allows you to upload a logo for the resource. The logo should be 50px high. For more information, see How do I upload and crop icons |
| Title | The name of the app, to be displayed on the page where users approve the app's access to their resources. |
| Sub-Title | A subtitle or tag line for the app, to be displayed below the app title on the page where users approve the app's access to their resources. |
| Website URL | The URL for the app's website. |
| Description | Represents the description of the app that displays below the sub-title (for example, This is the app description). |
| Legal Disclaimer | Copyright/legal information for the app, to be displayed at the bottom of the page where users approve the app's access to their resources. For example: 2016 {Company Name} All rights reserved. |
Access Token Settings:
| Setting | Explanation / possible values |
|---|---|
| Token Type | The access token type the app will use for OAuth. Choose from valid options or leave as Default, indicating no preference. |
| Authentication Method | Choose from the list of authentication methods supported by the OAuth Provider, or choose Provider Default to use any of the authentication methods allowed by the provider. By default, the Akana OAuth Provider allows all authentication methods except that a confidential client is not allowed to use none. |
Authentication Settings:
| Setting | Explanation / possible values |
|---|---|
| Authentication Method | One or more authentication mechanisms that the app will use to authenticate with the OAuth Provider. You must first provide the applicable values. To use a client secret option, make sure the shared secret is set; to use Private Key JWT, upload the credentials via Credentials > Upload Keystore. |
| Application Type | Choose whether the app is confidential (capable of maintaining the confidentiality of the client credentials) or public (incapable of maintaining the confidentiality of the credentials). For more information, see What are the OAuth 2.0 Client Types? |
| Redirect URI | The URL the user is redirected to after authentication/authorization. Specify all redirect URLs that are valid for the app. |
ID Token Settings:
| Setting | Explanation / possible values |
|---|---|
| ID Token Signing Algorithm | The algorithm that will be used for signing OpenID Connect ID tokens. Choose from valid options or leave as Provider Default, indicating no preference. |
| ID Token Encryption Key Management Algorithm | The algorithm that will be used for key encryption for OpenID Connect ID tokens. Choose from valid options, specify dir to use direct JWE encryption, or leave as Provider Default, indicating no preference. |
| ID Token Content Encryption Algorithm | The algorithm that will be used for content encryption for OpenID Connect ID tokens. Choose from valid options or leave as Provider Default, indicating no preference. |
| Require Authentication Time Claim | Check the box if you want the provider to include the auth_time claim in OpenID Connect ID tokens indicating the time at which the user was authenticated. Some clients choose to require this so they can validate the age of the claim. |
How do I configure OAuth credentials?
If the API your app is connected to uses OAuth 1.0a (with the Authentication Code and Resource Owner Password Credentials grant types), or OAuth 2.0 (with Authentication Code and Implicit grant types), you will need to:
- Configure a Shared Secret or Public Keys. See How do I regenerate a shared secret?, How do I import a certificate signing request?, or How do I import an X.509 certificate?
- Configure a Resource URL and other values in the app's OAuth Profile page. See How do I configure my app's OAuth profile settings?
- Configure the Resource Owner OAuth Authorization page which allows app developers to provide different details for branding to app users and customers. See How do I configure a Resource Owner OAuth Authorization page for my app?
How do I configure a Resource Owner OAuth Authorization page for my app?
If the API your app is connected to uses an OAuth "Authentication Code" grant and you've configured a Redirect URL and Application Type using the instructions given in How do I configure OAuth credentials?, the next step is to configure a Resource Owner OAuth Authorization page. This page allows app developers to provide different details for branding to app users.
To configure a Resource Owner OAuth Authorization page for your app:
- Navigate to My Apps.
- Select the App Name on the summary listing. The App Details page displays.
- Select an app version from the Current Version drop-down menu.
- Click OAuth Profile.
- On the OAuth Profile page, in the Branding section, specify information that will determine how your app is represented on the OAuth authorization page. For explanations of the fields available, refer to Branding Settings.
- Click Save.
The image below gives an idea of how your branding page will look to your user at runtime.
 |
|
What are the OAuth 2.0 Client Types?
- Confidential Client—This client type is an application that is capable of keeping a client password confidential to the world. This client password is assigned to the client app by the authorization server. This password is used to identify the client to the authorization server, to avoid fraud. An example of a confidential client could be a web app, where no one but the administrator can get access to the server, and see the client password.
- Public Client—This client type is an application that is not capable of keeping a client password confidential. For instance, a mobile phone application or a desktop application that has the client password embedded inside it. Such an application could get cracked, and this could reveal the password. The same is true for a JavaScript application running in the user's browser. The user could use a JavaScript debugger to look into the application, and see the client password.