4.2. Authenticating to REST Services. Q u i c k R e f e r e n c e G u i d e. 1. IdentityX 4.2 Updates

Transcription

1 4.2 Authenticating to REST Services Q u i c k R e f e r e n c e G u i d e In IdentityX 4.1, REST services have an authentication and signing requirement that is handled by the IdentityX REST SDKs. In order for an application to connect to IdentityX, it must have a token. A token is a cryptographic key shared between IdentityX and the Relying Party Server Application. The key is used to sign requests to and verify the responses from IdentityX. Each token has an associated set of permissions within IdentityX. These permissions determine the capabilities of the calling application. In addition to verifying the signature on the request from a Relying Party Server Application (or any client SDK), IdentityX will check that the token associated with the signature has the appropriate permission to perform the operation on the resource or resources. Tokens can be permanent or session tokens. The IdentityX REST SDK currently supports the use of an existing permanent token, or the creation of a session token through credentials. Session tokens can be created at a separate endpoint (/sessiontokens) and this is protected by a different authentication scheme very similar to Basic HTTP. In IdentityX 4.1, REST services are protected by two separate filters: One securing the /sessiontoken endpoint (requiring custom Basic HTTP authentication or SAML), and One for all the other endpoints, requiring Digest authentication (with shared key). 1. IdentityX 4.2 Updates As part of IdentityX 4.2, IdentityX offers the ability for customers to make REST calls against the IdentityX server using different authentication mechanisms: Basic HTTP (NEW) Digest with HMAC (shared key) Digest with public/private keys (NEW) SAML SAML + Digest (NEW) Customized Basic HTTP A combination of mechanisms can be employed. For example, a session token can be obtained from the /sessiontokens endpoint using one of the following Basic HTTP, SAML, Custom Basic Http and then the session token can be used to access the REST services by means of a Digest scheme. Another option is to configure IdentityX to offer access to all services based on Basic HTTP or SAML. Although different scenarios and combinations are possible, only the practical ones are described in this guide. One of the constraints is that Digest authentication always has to be on because in Release 4.2 the Administration UI requires Digest authentication in order to access the REST Services. May 26, 2017 Page 1 of 5

2 Regardless of the mechanism, the authorization information is passed to the server inside a header. The header name is by default Authorization but can also be configured in the IdentityX server and in the IdentityX client SDK to be in a different header. 2 Main Authentication Scenarios 1. Basic HTTP This is the classic Basic HTTP scheme. Feedback from customers who have evaluated IdentityX 4.1 indicate they want the ability to make REST calls against the IdentityX server without having to use the IdentityX REST SDK. Customers are used to being able to use tools like curl or postman to post JSON and get a JSON response. For this reason, Basic HTTP was introduced as an additional method of authentication. The Digest scheme is still accepted. However, if no Digest is attached then a header containing authentication details for the Basic HTTP scheme will be used instead. If two headers are present, one for the Digest scheme and one for Basic HTTP, the Digest scheme will take priority. Basic HTTP does not affect the /sessiontokens endpoint for this scenario. Therefore this endpoint will continue to be protected by the Custom Basic HTTP scheme in order to maintain compatibility with the Administration UI. A client will simply have to add the Authorization header according to the Basic HTTP spec. Most HTTP client tools have this capability, including the IdentityX client SDK. See IdentityX Java REST SDK Integration Guide for more details. Setting up Basic HTTP as an additional method of authentication is done at the tenant level. Using the Administration UI, a tenant administrator can enable Basic HTTP by navigating to the REST Authentication category of the System Configuration and setting the property REST Authentication Mode to be Digest Plus Basic HTTP Authentication. This configuration is set to Digest by default. 2. Digest with HMAC By default the server is always configured to support both Digest schemes. The content of the authorizing header will depend on the scheme. To differentiate between the authentication schemes, the scheme name in the header will have a different value (Digest or JWS). This scheme is used by AdminUI to access the REST services once a token is obtained from a call to /sessiontokens endpoint. Setting up a REST client to use this scheme can be difficult since a digest has to be calculated on the request and a signature has to be verified on the response. Applications would normally use the IdentityX client SDK library that provides support to abstract this digest calculation and verification so the relying party does not need to handle this. In order to set up the client SDK to use this authentication scheme, a permanent token has to be obtained through the Administration UI. See IdentityX Java REST SDK Integration Guide for more details. May 26, 2017 Page 2 of 5

3 The server supports this scheme by default, no setup is necessary. 3. Digest with public/private Keys This scheme is similar to Digest with HMAC, however, instead of a shared secret it uses a public/private key pair in order to sign the MAC of the message. This makes the system more secure as no secret needs to be transmitted between the IdentityX server and the relying party application calling it. Also, instead of using a custom format for the content of the authentication header uses a JSON Web Token (JWT) format. This scheme in described in detail in the document IdentityX 4.2 QRG Asymmetric Key Signing and Signature. IdentityX client SDK supports this scheme. See IdentityX Java REST SDK Integration Guide for more details. Refer to the following documents: IdentityX 4.2 QRG - IdentityX SSM Key Management IdentityX 4.2 QRG - IdentityX SSM Key Rollover 4. SAML SAML can be used as a means of authentication to the /sessiontokens endpoint in order to obtain a temporary token that can be used to access the REST services. The typical scenario would be to set up a proxy between the browser and the web server hosting IdentityX. When a user tries to access the Administration UI they are redirected to an authentication page of a third party. After authentication, the third party server attaches a header containing a SAML assertion and redirects the request back to the IdentityX server. When starting on the client browser in SAML mode, the Administration UI does not display its own authentication screen (username/password) and attempts to access the /sessiontokens endpoint directly. This call is intercepted by the third party proxy and authenticated with a SAML header. A successful call to /sessiontokens results in the creation of a session token in Administration UI. The permissions on this token are determined based on the IdentityX roles configured for that tenant and the membership groups provided in the SAML assertion. The token is then used by the Administration UI to access the REST services via the Digest protocol. The header name containing the SAML assertion is configurable and can contain plain text in one line or a base64 encoding of the assertion. The SAML document is normally obtained following a successful authentication to a third party server and will contain at least the name of the authenticated user and details about their membership groups. The requirements on the SAML assertion are: It has to be a well-formed XML document in the SAML2 format. It has to be signed and include a Signature element. The certificate that can be used to validate the signature has to be included in the Signature element. May 26, 2017 Page 3 of 5

4 If it contains a Conditions element with NotBefore and NotAfter attributes, these will be validated by IdentityX. It has to contain an Attribute element specifying a list of groups the user is a member of. The name of the attribute is configurable in IdentityX. A sample of SAML is provided below: <saml:attributestatement> <saml:attribute Name="membership" NameFormat="urn:oasis:names:tc:SAML:2.0:assertion"> <saml:attributevalue xsi:type="xs:string">cn=isa,ou=daon,dc=test</saml:attributevalue> <saml:attributevalue xsi:type="xs:string">cn=uni,ou=daon,dc=test</saml:attributevalue> </saml:attribute> </saml:attributestatement> The IdentityX server will attempt to map these groups to IdentityX roles based on the externalid property of the role. Each role has a set of permissions associated and all the matching roles will have their permissions joined in order to determine the final permission set of the current user. It has to contain an Attribute element specifying the name of the authenticated user. This will be used for logging and auditing purposes and also displayed by AdminUI. The authentication mechanism The IdentityX server first checks that the header content is a valid XML document and validates it according to the SAML2 scheme. After this, the server verifies that the assertion signature is correct using the included certificate. Only one signature and one certificate are allowed in the document. The public key in the certificate is validated (checked if not expired). Next step is to validate the certificate. IdentityX implements two ways of validation for this: For explicit validation, the certificate passed in SAML has to be identical with a preconfigured cert in IdentityX. For path based validation, intermediate certs and the CA certificate can be preconfigured on the server. In the end, the NotBefore and NotAfter conditions of the SAML document are validated. NOTE: Unlike Basic HTTP that can be configured at tenant level, SAML authentication is configured at system level. SAML assertions signature will be checked using the same certs for all tenants in the system. The client remains unchanged; normally there is a proxy that inserts the new SAML header. This is described in the Configuring IdentityX server for different authentication modes document. May 26, 2017 Page 4 of 5

5 5. SAML + Digest In the previous scenario only, the authentication to the /sessiontokens endpoint is based on SAML. Once a session token is obtained by the Administration UI, this token is then used to provide authentication to the REST services via Digest authentication. However, since the third party proxy intercepts all the calls to IdentityX, a SAML header can be added to all requests in order to add to the security of the Digest scheme. For this scheme, two separate headers can be present in the message: one containing a SAML assertion and one containing the Digest message. Both headers will be evaluated by IdentityX and authentication will need to be passed for both for a successful request. The Digest header is mandatory; the SAML header is optional. The client remains unchanged; normally there is a proxy that inserts the new SAML header. This is described in the Configuring IdentityX server for different authentication modes document. 6. Customized Basic Http This scheme is created for the purpose of the Administration UI being able to access the /sessiontoken endpoint. It is the same as Basic HTTP but with a different scheme name in the header value so the browser won t interfere with the session. Many browsers will take control of the session where Basic HTTP is used, remembering the username and the password. For this reason, in order to be fully flexible, we use a different scheme name for what practically is a simple Basic HTTP. When this scheme is employed, access to the REST services is normally done through Digest. May 26, 2017 Page 5 of 5