Policy Configurations for OAuth security

Just like any other security policy, Sentinet supports OAuth security policy with the Policy configurations, which are configured as WCF bindings.

Microsoft WCF libraries do not provide bindings for OAuth security, which is why Sentinet provides its own custom bindings for that security type. Sentinet users do not have to register these custom bindings or their extensions, as they are an integral part of the product and can be used out-of-the-box.

Sentinet WCF custom binding for OAuth security uses its own custom Binding Element Extension called webOAuthSecurity. This is the security binding element that implements the OAuth protocol, and it is used in the custom binding in place of the WCF standard security binding element.

The webOAuthSecurity binding element extension can be configured with either Service OAuth security or Client OAuth security, depending on where OAuth security needs to be configured, on the virtual service inbound or outbound side.

Sentinet provides out-of-the-box two shared Policy templates, REST - OAUTH TEMPLATE (Service) and REST - OAUTH TEMPLATE (Client) (see Policies chapter for more details). These two policies are registered in the Sentinet Repository root folder along with other policies shipped with the default product installation and they can be used as templates for other shared or private policies that are derived from them. Effectively, both templates provide "documentation" for the complete format of the service and client binding configurations.

Both policy templates use the same common format of the WCF <customBinding> binding configuration:

<bindings>  
  <customBinding>
      <binding name="WebOAuthSecurityBinding">
          <webOAuthSecurity>
          ....
          </webOAuthSecurity>
          <webMessageEncoding />
          <httpsTransport manualAddressing="true" />
      </binding>
  </customBinding>
</bindings>

The most important element in this custom binding is <webOAuthSecurity> binding element extension.

Note

<webMessageEncoding /> and <httpsTransport manualAddressing="true" /> are standard WCF binding element extensions. They are used in the custom bindings to configure them for REST APIs standard message encoding with HTTPS protocol. These can be replaced with other suitable binding element extensions (for example with <httpTransport manualAddressing="true" /> for HTTP protocol (even though this is not recommended for security reasons, especially in production environments).

<webOAuthSecurity> element must be configured with either <serviceSettings> sub-element for the Service OAuth security or with <clientSettings> sub-element for the Client OAuth security:

<webOAuthSecurity>  
  <!--- service security-->
  <serviceSettings>    
  ...
  </serviceSettings> 
</webOAuthSecurity>

<webOAuthSecurity>  
  <!--- client security-->
  <clientSettings>    
  ...
  </clientSettings> 
</webOAuthSecurity>

Service OAuth security configuration

The <webOAuthSecurity> element has the following optional attributes:

  • metadataEndpoint -- configures the address of the OAuth server endpoint that provides OAuth server metadata document. Providing the known address of the OAuth server metadata endpoint simplifies the further configuration of the binding, because in this case, the binding does not have to be configured with "up-front" knowledge of the OAuth server specifics like OAuth server signature keys or server certificates that are used to sign JWT tokens. This knowledge will be acquired by the binding at runtime by requesting the OAuth server metadata document from the specified metadataEndpoint address.

  • metadataType -- configures the type of the OAuth server metadata endpoint. Valid values are:

The <serviceSettings> sub-element has the following optional attributes:

  • tokenType -- specifies the token type expected from the OAuth server. Valid token types are:

    • Jwt -- JWT token is expected from the OAuth server. This is the default attribute value.

    • Reference -- Reference token is expected from the OAuth server.

  • cacheLifetime -- maximum time to cache validated OAuth tokens before making another token validation request. Default value is 1 hour, "01:00:00".

    If tokenType value is Reference, then the attributes below can be specified.

  • tokenValidationEndpoint -- (required attribute if tokenType= Reference). Specifies the address of the OAuth server's token validation (introspection) endpoint.

  • tokenParameterName -- specifies the name of the query parameter, form parameter or HTTP header that contains the value of the access token itself when Sentinet must call token validation endpoint. The default value is token.

  • tokenParameterType -- specifies the method of sending an access token value when calling token validation endpoint. Valid values are:

    • FormParameter -- Access token is sent in the Forms parameter. This is the default attribute value.

    • QueryParameter -- Access token is sent in the Query Parameter.

    • HttpHeader -- Access token is sent in the HTTP header.

  • tokenFormatString -- optional attribute that specifies additional format for the access token value when Sentinet calls the token validation endpoint. For example, Bearer {0} value may result in the following Query Parameter: access_token=Bearer xxxxxx, where xxxxx is the token value. The default attribute value is an empty string if attribute is not specified, in which case the token value is not formatted.

  • tokenAuthorizationHeader -- optional attribute that sets the value of the Authorization HTTP header when Sentinet calls the token validation endpoint. If this attribute is not provided, then Authorization HTTP header is not sent to the token validation endpoint. If tokenParameterType attribute above is set to HttpHeader and tokenParameterName attribute above is set to Authorization, then this tokenAuthorizationHeader attribute is ignored.

  • tokenParameters -- optional attribute that specifies any additional query or form parameters that Sentinet can send to the token validation endpoint. This attribute value must be Url-encoded, ampersand-separated list of additional query or form parameters. This list is sent as:

    • Uri query parameters if tokenParameterType attribute above is set to QueryParameter or HttpHeader.

    • Forms parameter in the message body if tokenParameterType attribute above is set to FormParameter.

  • validationTimeout -- communication timeout for OAuth server token validation endpoint, Default value is 1 minute, "00:01:00".

  • requireToken -- Boolean flag that indicates that Sentinet must find a valid OAuth token in the request. The default value is true. If value is false, Sentinet OAuth binding will allow requests without an OAuth token to reach into the virtual service (where it might be further inspected and validated by Sentinet Access Control engine and its Claim Authorization Expression).

The <serviceSettings> sub-element has its own optional sub-elements:

  • <issuers>    
  <add value="https://OAuthServer/oauth" />
</issuers>

    The XML section specifies the list of valid OAuth token issuers (OAuth servers). The issuers are identified by the issuer's Uniform Resource identifier URI. More than one issuer can be added to the list of the valid issuers. If the list is empty or the <issuers> element is not specified, then any issuer will be treated as valid.

    Note

    Empty issuer list does not necessarily imply a security risk in the configuration, as issuers may be validated later by the Sentinet Access Rule and its Claims Authorization Expression.

  • <audiences>   
  <add value="https://localhost/service" />
</audiences>

    The XML section specifies the list of valid OAuth token audiences. An audience is an identifier of the valid recipient or resource for which OAuth tokens are issued for. More than one audience can be added to the list of the valid audiences. If the list is empty or <audiences> element is not specified, then any audience will be treated as valid.

    Note

    Empty audience list does not necessarily imply a security risk in the configuration, as audience may be validated later by the Sentinet Access Rule and its Claims Authorization Expression.

    <signingCertificateReferences>   
  <add findValue="1b7acc520305bfdb4f7252daeb2177cc091faae1" storeLocation="LocalMachine" 
               storeName="My" x509FindType="FindByThumbprint" />
</signingCertificateReferences>

    If <webOAuthSecurity> binding element does not have a metadataEndpoint attribute (described above), then the binding will have to know the OAuth server X.509 identity(s) "up-front" and it should be specified in the binding itself. The identity specified in this XML section will be used if OAuth uses an X.509 certificate to sign JWT tokens. More than one certificate can be added to the OAuth server certificate identities list. Each certificate (public part of the certificate) specified in this XML section must be imported into Sentinet Node's Windows Certificates Store and referenced in this section by store location, store name and certificate search criteria as shown in the example above.

  • <signingCertificates>   
  <add encodedValue= "MIIDPjCCAiqgAwIBAgIQsRiM0jheFZhKk4..."/>
</signingCertificates>

    The XML section is similar in its purpose and function to the <signingCertificateReferences> section described above, except that it provides alternative means of specifying OAuth server certificate identities. Instead of referencing them in the Sentinet Node server certificate store, this section allows to specify the complete base64-encoded content of the public part of the OAuth server certificate. More than one certificate can be added to the OAuth server certificate identities list.

    Both <signingCertificateReferences> and <signingCertificates> sections can be configured with the binding resulting in the merged list of valid OAuth server certificates.

  • <signingRsaKeys>   
  <add kid="a3rMUgMFv9tPclLa6yF3zAkfquE" exponent="AQAB"
  modulus="qnTksBdxOiOlsmRNd-mMS2M3o1IDpK4uAr..." /> 
</signingRsaKeys>

    List of OAuth server's asymmetric public keys that are used to validate JWT RSA tokens issued by the OAuth server. This XML section will be used at runtime, if OAuth server uses its asymmetric public keys to sign issued JWT RSA tokens.

    • kid -- optional Key identifier that is used to resolve key references

    • exponent -- Base64-encoded RSA key exponent

    • modulus -- Base64-encoded key modulus

  • <signingSecrets>   
  <add kid="primary-key" secret="MTIzNDU2Nzg5MDEyMzQ1Ng==" /> 
</signingSecrets>

    List of OAuth server's symmetric public keys that are used to validate JWT HMAC tokens issued by the OAuth server. This XML section will be used at runtime, if the OAuth server uses its symmetric keys to sign issued JTW HMAC tokens.

    • kid -- optional Key identifier that is used to resolve key references

    • secret -- Base64-encoded symmetric secret key

    Important

    Even though <signingSecrets> element can be present in the policy configuration, it is recommended to be omitted here to avoid exposing secrets in clear text. Instead, it is recommended to use explicit Private or Shared Identity of type OAuth Service Credentials to specify list of kid and secret pairs.

Note

If metadataEndpoint is unknown or is not used, Sentinet users must consult the OAuth server documentation that describes OAuth server certificates and/or RSA and symmetrical keys. Sentinet users in this case will use information provided in the documentation to identify which XML section described above should be used with the Sentinet OAuth binding configuration.

Client OAuth security configuration

he <webOAuthSecurity> element has the following optional attributes:

  • metadataEndpoint -- configures address of the OAuth server endpoint that provides the OAuth server metadata document. Defining the known address of the OAuth server metadata endpoint removes the need to specify tokenEndpoint attribute of the clientSettings element described below. The knowledge of the tokenEndpoint address in this case will be acquired by the binding at runtime by requesting the OAuth server metadata document from the specified metadataEndpoint address.

  • metadataType -- configures the type of the OAuth server metadata endpoint. Valid values are:

The <clientSettings> sub-element has the following attributes. All attributes except clientId and clientSecret are optional.

  • tokenEndpoint -- specifies endpoint address of the OAuth server from which Sentinet virtual service must acquire OAuth token. The metadataEndpoint attribute of the <webOAuthSecurity> element can be provided instead of the tokenEndpoint attribute.

  • clientId -- specifies id of the OAuth client application registered with OAuth server as a valid API or resources consumer.

  • clientSecret -- specifies client secret value of the OAuth client application registered with OAuth server as a valid API or resources consumer.

    Important

    Instead of exposing OAuth secrets in clear text in the Policy configuration, it is recommended to specify these two particular secrets by assigning them via a Private or a Shared Identity as an endpoint’s Outbound Client Identity, in which case OAuth policy configuration is allowed to omit specifying Client Id and Client Secret settings.

  • authenticationType -- specifies how client application credentials will be sent in the request for OAuth token to the OAuth server, where client credentials are clientId and clientSecret described above. Valid authentication types are:

    • FormPost-- credentials will be sent in HTTP Form POST format. This is the default attribute value.

    • BasicAuthentication-- client credentials will be sent over standard Basic Authentication security mechanism in HTTP header.

  • authenticationFlow -- specifies which authentication flow will be used to send OAuth token in the request. Valid authentication flows are:

  • scopes -- specifies list of valid scopes of the access request. Multiple scope values in the list must be space character separated.

  • audience -- specifies audience. An audience is an identifier of the valid recipient or resource for which OAuth tokens are issued.

  • parameters -- any additional parameters that might be needed in the request for an OAuth token, which will be added as a URI Query String-formatted and URL-encoded name-value pairs. For example: parameters="myparameter1=MyValue1&myparameter2=MyValue2".

  • requestTimeout -- communication timeout with OAuth server. Default value is 1 minute, "00:01:00".

  • minimumCacheLifetime – minimum time to locally cache OAuth tokens on the Sentinet Node, which do not have their own, server-generated expiration times. Default value is “00:00:00”, which means that tokens without their own expiration times will not be cached.

  • maximumCacheLifetime – maximum time to locally cache the unexpired OAuth tokens on the Sentinet Node, which are returned by OAuth server. Default value is 1 hour, “01:00:00”. maximumCacheLifetime can be less than the server specifies as the expiration time, in which case tokens are refreshed by Sentinet more often than the server would.