Package com.coveo.saml

Class SamlClient

java.lang.Object
com.coveo.saml.SamlClient
public class SamlClient extends Object

  • Constructor Details

    • SamlClient

      public SamlClient(String relyingPartyIdentifier, String assertionConsumerServiceUrl, String identityProviderUrl, String responseIssuer, List<X509Certificate> certificates, SamlClient.SamlIdpBinding samlBinding) throws SamlException
      Constructs an SAML client using explicit parameters.
      Parameters:
      relyingPartyIdentifier - the identifier of the relying party.
      assertionConsumerServiceUrl - the url where the identity provider will post back the SAML response.
      identityProviderUrl - the url where the SAML request will be submitted.
      responseIssuer - the expected issuer ID for SAML responses.
      certificates - the list of base-64 encoded certificates to use to validate responses.
      samlBinding - what type of SAML binding should the client use.
      Throws:
      SamlException - thrown if any error occur while loading the provider information.

    • SamlClient

      public SamlClient(String relyingPartyIdentifier, String assertionConsumerServiceUrl, String identityProviderUrl, String responseIssuer, List<X509Certificate> certificates) throws SamlException
      Constructs an SAML client using explicit parameters.
      Parameters:
      relyingPartyIdentifier - the identifier of the relying party.
      assertionConsumerServiceUrl - the url where the identity provider will post back the SAML response.
      identityProviderUrl - the url where the SAML request will be submitted.
      responseIssuer - the expected issuer ID for SAML responses.
      certificates - the list of base-64 encoded certificates to use to validate responses.
      Throws:
      SamlException - thrown if any error occur while loading the provider information.

    • SamlClient

      public SamlClient(String relyingPartyIdentifier, String assertionConsumerServiceUrl, String identityProviderUrl, String responseIssuer, X509Certificate certificate) throws SamlException
      Constructs an SAML client using explicit parameters.
      Parameters:
      relyingPartyIdentifier - the identifier of the relying party.
      assertionConsumerServiceUrl - the url where the identity provider will post back the SAML response.
      identityProviderUrl - the url where the SAML request will be submitted.
      responseIssuer - the expected issuer ID for SAML responses.
      certificate - the base-64 encoded certificate to use to validate responses.
      Throws:
      SamlException - thrown if any error occur while loading the provider information.

  • Method Details

    • getIdentityProviderUrl

      public String getIdentityProviderUrl()
      Returns the url where SAML requests should be posted.
      Returns:
      the url where SAML requests should be posted.

    • setInstantNow

      public void setInstantNow(Instant now)
      Sets the date that will be considered as now. This is only useful for testing.
      Parameters:
      now - the date to use for now.

    • setNotBeforeSkew

      public void setNotBeforeSkew(long notBeforeSkew)
      Sets by how much the current time can be before the assertion's notBefore. Used to mitigate clock differences between the identity provider and relying party.
      Parameters:
      notBeforeSkew - non-negative amount of skew (in milliseconds) to allow between the current time and the assertion's notBefore date. Default: 0

    • decodeAndValidateSamlResponse

      public SamlResponse decodeAndValidateSamlResponse(String encodedResponse, String method) throws SamlException
      Decodes and validates an SAML response returned by an identity provider.
      Parameters:
      encodedResponse - the encoded response returned by the identity provider.
      method - The HTTP method used by the request
      Returns:
      An SamlResponse object containing information decoded from the SAML response.
      Throws:
      SamlException - if the signature is invalid, or if any other error occurs.

    • redirectToIdentityProvider

      public void redirectToIdentityProvider(jakarta.servlet.http.HttpServletResponse response, String relayState) throws IOException, SamlException
      Redirects an HttpServletResponse to the configured identity provider.
      Parameters:
      response - The HttpServletResponse.
      relayState - Optional relay state that will be passed along.
      Throws:
      IOException - thrown if an IO error occurs.
      SamlException - thrown is an unexpected error occurs.

    • processPostFromIdentityProvider

      public SamlResponse processPostFromIdentityProvider(jakarta.servlet.http.HttpServletRequest request) throws SamlException
      Processes a POST containing the SAML response.
      Parameters:
      request - the HttpServletRequest.
      Returns:
      An SamlResponse object containing information decoded from the SAML response.
      Throws:
      SamlException - thrown is an unexpected error occurs.

    • fromMetadata

      public static SamlClient fromMetadata(String relyingPartyIdentifier, String assertionConsumerServiceUrl, Reader metadata) throws SamlException
      Constructs an SAML client using XML metadata obtained from the identity provider.

      When using Okta as an identity provider, it is possible to pass null to relyingPartyIdentifier and assertionConsumerServiceUrl; they will be inferred from the metadata provider XML.

      Parameters:
      relyingPartyIdentifier - the identifier for the relying party.
      assertionConsumerServiceUrl - the url where the identity provider will post back the SAML response.
      metadata - the XML metadata obtained from the identity provider.
      Returns:
      The created SamlClient.
      Throws:
      SamlException - thrown if any error occur while loading the metadata information.

    • fromMetadata

      public static SamlClient fromMetadata(String relyingPartyIdentifier, String assertionConsumerServiceUrl, Reader metadata, SamlClient.SamlIdpBinding samlBinding) throws SamlException
      Constructs an SAML client using XML metadata obtained from the identity provider.

      When using Okta as an identity provider, it is possible to pass null to relyingPartyIdentifier and assertionConsumerServiceUrl; they will be inferred from the metadata provider XML.

      Parameters:
      relyingPartyIdentifier - the identifier for the relying party.
      assertionConsumerServiceUrl - the url where the identity provider will post back the SAML response.
      metadata - the XML metadata obtained from the identity provider.
      samlBinding - the HTTP method to use for binding to the IdP.
      Returns:
      The created SamlClient.
      Throws:
      SamlException - thrown if any error occur while loading the metadata information.

    • fromMetadata

      public static SamlClient fromMetadata(String relyingPartyIdentifier, String assertionConsumerServiceUrl, Reader metadata, SamlClient.SamlIdpBinding samlBinding, List<X509Certificate> certificates) throws SamlException
      Constructs an SAML client using XML metadata obtained from the identity provider.

      When using Okta as an identity provider, it is possible to pass null to relyingPartyIdentifier and assertionConsumerServiceUrl; they will be inferred from the metadata provider XML.

      Parameters:
      relyingPartyIdentifier - the identifier for the relying party.
      assertionConsumerServiceUrl - the url where the identity provider will post back the SAML response.
      metadata - the XML metadata obtained from the identity provider.
      samlBinding - the HTTP method to use for binding to the IdP.
      certificates - list of certificates.
      Returns:
      The created SamlClient.
      Throws:
      SamlException - thrown if any error occur while loading the metadata information.

    • decodeAndValidateSamlLogoutResponse

      public SamlLogoutResponse decodeAndValidateSamlLogoutResponse(String encodedResponse, String method) throws SamlException
      Decodes and validates an SAML response returned by an identity provider.
      Parameters:
      encodedResponse - the encoded response returned by the identity provider.
      method - The HTTP method used by the request
      Returns:
      An SamlResponse object containing information decoded from the SAML response.
      Throws:
      SamlException - if the signature is invalid, or if any other error occurs.

    • decodeAndValidateSamlLogoutRequest

      public void decodeAndValidateSamlLogoutRequest(String encodedRequest, String nameID, String method) throws SamlException
      Decodes and validates an SAML logout request send by an identity provider.
      Parameters:
      encodedRequest - the encoded request send by the identity provider.
      nameID - The user to logout
      method - The HTTP method used by the request
      Throws:
      SamlException - if the signature is invalid, or if any other error occurs.

    • setSPKeys

      public void setSPKeys(String publicKey, String privateKey) throws SamlException
      Set service provider keys.
      Parameters:
      publicKey - the public key
      privateKey - the private key
      Throws:
      SamlException - if publicKey and privateKey don't form a valid credential

    • setSPKeys

      public void setSPKeys(X509Certificate certificate, PrivateKey privateKey) throws SamlException
      Set service provider keys.
      Parameters:
      certificate - the certificate
      privateKey - the private key
      Throws:
      SamlException - if publicKey and privateKey don't form a valid credential

    • addAdditionalSPKey

      public void addAdditionalSPKey(String publicKey, String privateKey) throws SamlException
      Add an additional service provider certificate/key pair for decryption.
      Parameters:
      publicKey - the public key
      privateKey - the private key
      Throws:
      SamlException - if publicKey and privateKey don't form a valid credential

    • addAdditionalSPKey

      public void addAdditionalSPKey(X509Certificate certificate, PrivateKey privateKey)
      Add an additional service provider certificate/key pair for decryption.
      Parameters:
      certificate - the certificate
      privateKey - the private key

    • clearAdditionalSPKeys

      public void clearAdditionalSPKeys()
      Remove all additional service provider decryption certificate/key pairs.

    • getAttributes

      public static Map<String,String> getAttributes(SamlResponse response)
      Gets attributes from the IDP Response
      Parameters:
      response - the response
      Returns:
      the attributes

    • getSamlRequest

      public String getSamlRequest() throws SamlException
      Builds an encoded SAML request.
      Returns:
      The base-64 encoded SAML request.
      Throws:
      SamlException - thrown if an unexpected error occurs.

    • getLogoutRequest

      public String getLogoutRequest(String nameId) throws SamlException
      Gets the encoded logout request.
      Parameters:
      nameId - the name id
      Returns:
      the logout request
      Throws:
      SamlException - the saml exception

    • getSamlLogoutResponse

      public String getSamlLogoutResponse(String status) throws SamlException
      Gets saml logout response.
      Parameters:
      status - the status code @See StatusCode.java
      Returns:
      saml logout response
      Throws:
      SamlException - the saml exception

    • getSamlLogoutResponse

      public String getSamlLogoutResponse(String status, String statMsg) throws SamlException
      Gets saml logout response.
      Parameters:
      status - the status code @See StatusCode.java
      statMsg - the status message
      Returns:
      saml logout response
      Throws:
      SamlException - the saml exception

    • processLogoutRequestPostFromIdentityProvider

      public void processLogoutRequestPostFromIdentityProvider(jakarta.servlet.http.HttpServletRequest request, String nameID) throws SamlException
      Processes a POST containing the SAML logout request.
      Parameters:
      request - the HttpServletRequest.
      nameID - the user to log out.
      Throws:
      SamlException - thrown is an unexpected error occurs.

    • processPostLogoutResponseFromIdentityProvider

      public SamlLogoutResponse processPostLogoutResponseFromIdentityProvider(jakarta.servlet.http.HttpServletRequest request) throws SamlException
      Processes a POST containing the SAML response.
      Parameters:
      request - the HttpServletRequest.
      Returns:
      An SamlResponse object containing information decoded from the SAML response.
      Throws:
      SamlException - thrown is an unexpected error occurs.

    • redirectToIdentityProvider

      public void redirectToIdentityProvider(jakarta.servlet.http.HttpServletResponse response, String relayState, String nameId) throws IOException, SamlException
      Redirects an HttpServletResponse to the configured identity provider.
      Parameters:
      response - The HttpServletResponse.
      relayState - Optional relay state that will be passed along.
      nameId - the user to log out.
      Throws:
      IOException - thrown if an IO error occurs.
      SamlException - thrown is an unexpected error occurs.

    • redirectToIdentityProviderLogout

      public void redirectToIdentityProviderLogout(jakarta.servlet.http.HttpServletResponse response, String statusCode, String statMsg) throws IOException, SamlException
      Redirect to identity provider logout.
      Parameters:
      response - the response
      statusCode - the status code
      statMsg - the stat msg
      Throws:
      IOException - the io exception
      SamlException - the saml exception