OAuth Authentication Module
The AMPS distribution includes a module that provides authentication through OAuth 2.0 to an external authorization server.
In this release, the OAuth authentication module is provided with AMPS, but is not loaded by default. This module is an optional extension to the AMPS product, and while it is included with the AMPS distribution, the module must be explicitly loaded, enabled, and configured.
When using this module, AMPS contacts an authorization server to confirm that a connection to AMPS has provided valid credentials to access AMPS.
This module does not provide entitlements, and would typically be used with another module to enforce entitlements.
When to Use the OAuth Module
The AMPS OAuth Authentication module can be a good option when:
The site does not have an existing authentication and entitlements infrastructure for AMPS.
The site has an existing OAuth authorization server deployed, and wants to use the same mechanism for access to AMPS.
Configuring AMPS to use OAuth Authentication
The OAuth Authentication module is included in the AMPS distribution, but is not loaded by default. To load the module in AMPS, add the following configuration item to the Modules block of the AMPS configuration file:
<Modules>
...
<Module>
<Name>oauth-authentication</Name>
<Library>libamps_oauth_authentication.so</Library>
<!-- You may specify options here, or where the module is used.-->
</Module>
...
</Modules>Options for the module may be set when the module is loaded or when the module is used for Authentication.
Options set when the module is loaded are inherited as the default values for all uses of the module in the instance. Options specified in an Authentication block override options set when the module is loaded.
The module supports the following options:
TokenEndpoint (required)
URI endpoint of the authorization server. The module will submit authorization requests to this URI.
There is no default for this option.
RedirectURI (required)
URI to which the authorization server redirects the user.
There is no default for this option.
ClientID (required)
Unique identifier issued by the authorization server for AMPS to identify itself to the authorization server.
There is no default for this option.
ClientSecret (required)
Secret used for AMPS to identify itself to the authorization server.
There is no default for this option.
GrantType
Type of OAuth grant or flow to request.
Default: authorization_code
RequestTimeout
The maximum amount of time to wait for the authorization server to return a result each request, in milliseconds. If the server does not return a response within the specified time, the module closes the connection and the request fails.
Increasing this timeout above the default value may produce potential stuck thread warnings if the authentication service is slow to respond.
Default: 5000
RetryCount
Sets the number of times to retry the request if retrieving the response fails for any reason.
Default: 0 (only try once)
HTTPHeader
Sets a header to add to the HTTP request.
The configuration can specify any number of HTTPHeader elements, and the module will provide each of the specified headers with the request.
There is no default for this option. If no HTTPHeader option is included, the module provides a standard set of headers.
For example, the following configuration loads the module and sets the module as the default authentication for all transports in the instance. The configuration then explicitly sets the admin interface to use AMPS default authentication (that is, developer mode authentication that allows access to all admin stats).
<AMPSConfig>
<Modules>
...
<Module>
<Name>oauth-authentication</Name>
<Library>libamps_oauth_authentication.so</Library>
<!-- Sets defaults for all uses of the module -->
<Options>
<TokenEndpoint>https://oauth.example.com/token</TokenEndpoint>
<ClientID>app-specific-id-from-server</ClientID>
<ClientSecret>validation-to-server</ClientSecret>
<RedirectURI>http://localhost:3000</RedirectURI>
<AllowUnverifiedPeer>true</AllowUnverifiedPeer>
</Options>
</Module>
...
</Modules>
<Authentication>
<Module>oauth-authentication</Module>
<Options>
<TokenEndpoint>https://oauth.example.com/token</TokenEndpoint>
<ClientID>app-specific-id-from-server</ClientID>
<ClientSecret>token-token-token</ClientSecret>
<RedirectURI>http://localhost:3000</RedirectURI>
<AllowUnverifiedPeer>true</AllowUnverifiedPeer>
</Options>
</Authentication>
<Admin>
<!-- set admin authentication back to AMPS default authentication
for development purposes -->
<Authentication>
<Module>amps-default-authentication-module</Module>
</Authentication>
</Admin>
<!-- All of these transports use the Authentication set at the instance level.
To use a different Authentication method, include an Authentication
block in the Transport definition. -->
<Transports>
<Transport>
<Name>json-tcp</Name>
<Type>tcp</Type>
<InetAddr>9007</InetAddr>
<MessageType>json</MessageType>
<Protocol>amps</Protocol>
</Transport>
<Transport>
<Name>any-tcp</Name>
<Type>tcp</Type>
<InetAddr>9090</InetAddr>
<Protocol>amps</Protocol>
</Transport>
</Transports>
</AMPSConfig>Using HTTPS for OAuth Requests
The OAuth Authentication Module optionally supports https entitlement requests. When the TokenEndpoint uses https as the scheme, the module will attempt to use https to connect to the web service.
By default, the module attempts to verify the identity of the remote web service, which requires a key file containing the key for the certificate authority that signed the certificate for the remote web service.
AMPS does not require that the certificate and key provided for outgoing https requests be the same certificates used for incoming SSL connections to AMPS. However, if you have configured AMPS to accept SSL connections from AMPS clients, the certificates you use for those connections are often suitable for outgoing web authentication module connections, and the same certificates can be provided in both sections of the configuration file.
Certificate
The certificate to use for the AMPS connection to the web service. When configured, this certificate can be provided to the web service if the web service requests client authentication for the connection.
There is no default for this parameter.
Key
The key file to use for the AMPS connection to the web service. When configured, this key can be used for client authentication if the web service requests client authentication for the connection.
There is no default for this parameter.
CAKey
The certificate authority key. When configured, this key can be used for the AMPS server to verify the identity of the web service.
There is no default for this parameter. The CAKey must be provided when AllowUnverfiedPeer is set to false, the default.
AllowUnverifiedPeer
Specifies whether AMPS requires the web service to identify itself. When this is set to false, the default, AMPS requires that the web service provides a certificate that can be verified with the configured CAKey.
Default: false
AllowSelfSigned
Specifies whether AMPS will accept self-signed certificates for https connections.
Default: false
Authentication Request Flow
This section describes the request flow for the OAuth Authentication module.
Logon request received from the client. This logon request includes an OAuth token received from the authorization server.
AMPS provides the OAuth token to the authorization server and requests an access token with the parameters configured on the module. The module contacts the authorization server at the
TokenEndpointspecified, providing the token from the client logon request and the parameters configured for the module.The authorization server returns a reply.
If the reply contains an access token, authentication succeeds.
If the reply is empty, contains an error, or does not contain an access token, authentication fails.
Last updated