Managed - OAuth2
- Chris Jones
- Thomas Legowo
- Michael Luecke
Servicely supports external OAuth providers for integration with third party systems.
OAuth2 Providers
Providers need to be defined in the SystemOAuthProvider table.
Field | Description |
|---|---|
Name | The name used to refer to the SystemOAuthProvider entry |
ClientID | The providers Client ID (supplied by the provider) |
Client Secret | The OAuth shared secret (supplied by the provider) |
Grant type | Currently only supports ‘Authorization Code’ |
Authorization URL | The providers OAuth2 Authorization Code URL. Used for the initial client redirect |
Token URL | The providers OAuth2 Token retrieval URL. Used by the Servicely Instance to request the actual authentication token. |
Scopes | And addition OAuth2 scopes required to be passed to the provider. |
Description | Free-text field to make any configuration notes about the provider. |
Example:
System API Outbound Tokens
SystemAPIOutboundToken records define a specific instance of the usage of a provider, with specific credentials. For example, you may have a single Google OAuth Provider, but have access multiple Google Services, each with different credentials. Each of those would be modelled as a SystemAPIOutboundToken.
Field | Description |
|---|---|
Name | The Name that will be used to refer to this token from the Integration |
Type | ‘OAuth2’ for an OAuth2 token |
OAuth Provider | The SystemOAuthProvider configuration to use |
OAuth Prompt | Allows specification of the OAuth ‘prompt’ parameter. Different providers have different requirements for this parameter, and some also may require different options at different times in the lifecycle. For example, for Microsoft Azure, you can initially specify ‘consent’ and authenticate as an administrator to apply and authorize the required permissions to the Azure application, and then change to ‘select_account’ and re-authenticate as an unprivileged user. Microsoft reference: |
Active | The token can be deactivated by setting this to false |
State | Shows the current state of the token |
Expires | If the provider returns an expiry time, this field will be set to the token expiry time. |
Scopes | Any OAuth scopes to be sent to the provider. Will override the scopes set on the Provider record itself. |
LastMessage | If an error occurs when requesting the tokens, this field will be populated with the error message. |
Base URL | New in 1.9: Used for informational purposes to highlight what a token is for. |
Example:
To request a new token from the provider, press the ‘Get authorization token’ button. You should be presented with the providers sign in page. Example below for a Microsoft email authentication setup
After authorization, you should be returned to the SystemAPIOutboundToken form.
Using from the Scripting environment
To use the SystemAPIOutboundToken from the Scripting environment, simply call the ‘apiTokenAuth' method of any of the outbound HTTP methods. The OAuth2 signature will be applied, and any expired tokens will automatically be refreshed before the request is made.
Related content
Servicely Documentation