OAuth¶
AMI supports OAuth integration for easy user credential management.
Overview¶
3forge supports a variety of authentication methods for AMI including OAuth for easy access control to your layouts. To use, you will need the 3forge OAuth plugin and the details of your OAuth credentials manager, for example: Okta.
Note
3forge supports Okta integration directly. To configure AMI to use Okta credentials, please navigate here.
Setup¶
You will need to ensure your identity provider has OAuth 2.0 Authentication enabled, then do the following:
- Find your identity provider URL.
- Register a new Web App (AMI) with the identity provider and provide a sign-in URL. This will be used to configure the property
oauth.redirect.uri
.- We recommend also providing a logout redirect URL, however this is optional.
- Add the properties listed below to your
local.properties
for minimal configuration.
Minimal Configuration¶
These are the minimum required properties to enable OAuth for AMI. For detailed information on each property and additional properties, see the properties section below.
Properties¶
Required¶
-
Default: N/A
- Class that implements an AmiWebSSOPlugin.
- Use
com.f1.ami.web.AmiWebOAuthPluginImpl
.
-
Default: N/A
- Domain of the OAuth server account (https://someoauthprovider.com).
-
Default: N/A
- AMI logout page (to be suffixed at the end of your AMI Web address).
- E.g:
/loggedout.htm
.
-
Default: N/A
- 3forge AMI Url for OAuth server to redirect after login.
- E.g:
http://localhost:33332/oauthRedirectUrl/
. - Remember to configure this with your OAuth provider.
-
Default: N/A
- Client ID.
-
Default: N/A
- Client secret.
-
Default:
/oauth2/default/v1/authorize
- Authorization endpoint.
-
Default:
/oauth2/default/v1/logout
- Logout endpoint.
-
Default:
/oauth2/default/v1/token
- Token endpoint.
-
Default: N.A
- Space delimited scopes indicating the types of resources AMI will be requesting from the resource server.
- Use your email.
-
Default: N/A
- User email.
Optional¶
-
Default:
/oauth2/default/v1/token
- The endpoint to get the refresh token.
-
Default:
refresh_token
- The refresh grant type for obtaining a new access token.
-
Default:
null
- The refresh redirect uri.
-
Default:
null
- The refresh scope.
-
Default:
oauth.client.id
- The client ID after refresh.
-
Default:
oauth.client.secret
- The client secret after refresh.
-
Default: N/A
- The field from that the identity response uses to identity an AMI dev user.
- Email recommended.
-
- Comma delimited list of AMI devs corresponding to the field.
- E.g, the list of emails of AMI devs.
- If the value of the
isdev
field matches any of the values, the user gets AMI dev privileges.
1 2 |
|
1 2 |
|
1 |
|
-
Default: N/A
- List of users with the given role.
-
Default: N/A
- Key that contains the time the access token expires in.
- If not set, the token will note expire.
-
Default:
S256
- Code challenge method.
-
Default:
SHA-256
- Java hashing algorithm.
-
Default:
60
- Seconds to check refresh token expiration.
-
Default: N/A
- The 3forge AMI endpoint that triggers the build auth request.
-
Default:
false
- For detailed logging.
-
Default:
true
- Set to false to disable certificate validation for SSL.
-
Default:
false
- Set to true to enable access to AMI via both IP address and domain URL.
- Requires both URLs to be registered in your OAuth provider's setting.
OAuth for Okta¶
The Okta plugin is a specific version of the OAuth Plugin, see below for the list of properties required:
-
Default: N/A
- Class that implements an AmiWebSSOPlugin. For Okta, use
com.f1.amioktaauth.AmiOktaOauthPlugin
.
- Class that implements an AmiWebSSOPlugin. For Okta, use
- Default: N/A - Client ID of the application registered to authenticate via Okta.
-
Default: N/A
- Client secret of the application registered to authenticate via Okta.
-
Default:
http://localhost:33332/oktaAuthFinished/
- The uri Okta will use to redirect the user once authentication is complete.
- Defaults to the URL of the AMI Web instance.
- This uri must match with the one configured in Okta account.
-
Default: N/A
- The domain of the Okta account (<https://something.okta.com>).
-
Default: N/A
- Space delimited scopes indicating the types of resources AMI will be requesting from the resource server.
- Use your OpenID email.
-
Default:
/
- URL to redirect to when logged out, default is
/
, which directs to login page. - We recommend setting this to a specific page address (e.g:
/loggedout.htm
) for a logged out page instead which is useful for OAuth.
- URL to redirect to when logged out, default is
-
Default: N/A
- The uri Okta will redirect to when a user logs out.
- Can only be used if
oauth.single.logout.enabled
is set totrue
, otherwise no behavior occurs. - See the Okta documentation for more information.
-
Default:
false
- Whether SLO should be enabled.
- Can be used with
oauth.logout.redirect.uri
to redirect users to a specific page.
-
Default:
/oauth2/default/v1/authorize
- Okta authorization endpoint.
/oauth2/default/v1/logout
1 |
|
-
Default:
/oauth2/default/v1/token
- Okta token endpoint.
-
Default:
S256
- Okta code challenge method.
-
Default:
SHA-256
- Java hashing algorithm used to verify the code challenge.
- Default:
email
- The field from Okta identity response to use as the AMI username. -
Default: N/A
- The field from Okta identity response use to identity an AMI admin user (Recommended).
-
Default: N/A
- Comma delimited list of AMI admins.
- If the value of the
isadmin
field matches any of the values, the user gets AMI admin privileges. Otherwise the user will be in user mode.
-
Default: N/A
- The field from Okta identity response use to identity an AMI dev user (Recommended).
-
- Comma delimited list of AMI devs.
- If the value of the
isdev
field matches any of the values, the user gets AMI dev privileges.
-
Default:
false
- For detailed logging.
-
Default:
60
- Controls polling frequency for a refresh token and also the frequency of the reaper thread to check on the SSO session.
Custom OAuth Plugin¶
The AMI OAuth plugin handles authorization code and access token requests that are needed for authenticating to AMI.
By extending the 3forge AMI OAuth plugin, you can create your own Ami OAuth Plugin if you have custom requirements for access control or entitlements.
There are three main methods in the 3forge AMI OAuth Plugin: buildAuthRequest
, processResponse
, and createAmiUserSSOSession
.
Main Components¶
buildAuthRequest()
-
- Responsible for creating the URL for the Authorization Code request.
processResponse()
-
- Responsible for processing the response from the Authorization Code request, then building an Access Token request.
- Once it obtains an access token, it needs to return an
AmiAuthUser
.
createAmiUserSSOSession()
-
- Responsible for creating the
AmiAuthUser
andOAuthSSO
Session. - The AmiAuthUser can be used to set user session variables or restrict access to layouts.
- The OAuth Session is accessible in AMIScript by
session.getSsoSession()
.
- Responsible for creating the