Help

Page tree

Versions Compared

Old Version 1

changes.mady.by.user user-ac987

Saved on

compared with

New Version Current

changes.mady.by.user Erin Martin

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Companyname

...

SAML

...

-based single sign-on (SSO) is a leading method for providing federated access to multiple applications

...

Companyname

...

Table of Contents
maxLevel3
excludeRelated Articles

SAML 2.0 Terminology

  • Identity Provider (IdP) – Software that provides Authentication Service and uses SAML 2.0 protocol to assert valid users.
  • Service Provider (SP) – Software that trusts an Identity Provider and consumes the services provided by the Identity Provider.
  • SAML Metadata XML – An XML document containing SAML2.0 configuration data.
  • SAML Assertion XML – An XML document that provides information about a user authenticated by an IdP.

Set up SAML 2.0 SSO

The following highlights the steps needed to integrate any SAML 2.0 IdP with an

Companyname
knowledgebase. Please refer to your IdP for instructions on how to configure access to a service provider, where
Companyname
acts as the SP. 

Note:

Companyname
only supports SP-initiated, not IdP-initated, SAML login.

Prerequisites

  • Administrator-level login credentials for
    Companyname
    and your SAML provider.
  • Obtain the configuration details from your IdP. These are typically provided in an XML file, commonly known as IdP SAML Metadata XML. Download the XML file from your IdP. If your IdP does not provide the configuration via XML file, you must obtain the following details from the Identity Provider:
    • IdP Entity
    • IdP Login
    • IdP Logout URL
    • IdP X.509 certificate
  • Note down the SAML Attribute names containing user groups and teams if you will create users in
    Companyname
    during login events.

When you configure SAML SSO in

Companyname
, you will have the option to create users in
Companyname
when they first log in. If you choose this option, you'll also need to select which default groups and teams the user is assigned to, or map them from SAML attributes. You'll need the exact names of the SAML attributes containing the user's groups, teams, and Primary Team.

...

Companyname

Follow these steps in

Companyname
to configure the SAML connection.

...

Companyname

...

  1. Select the Enable SAML SSO checkbox. 
  2. Optionally, select the checkbox to Create SAML IdP Authenticated user in
    Companyname
    . This will create users in
    Companyname
     from those in the SAML system when the connection is first established. If this or the next option is selected, the User Field(s) Mapping tab will appear. 
  3. Optionally, select Update User fields on subsequent logins by an existing user. This will update the mapped user fields from SAML whenever the user logs in. If this option is selected, the User Field(s) Mapping tab will appear. 
  4. If the Create SAML IdP Authenticated user or Update User fields on subsequent logins by an existing user options were selected, choose a Persons table or subtable to map user fields from SAML to 
    Companyname
    . 

...

Companyname

...

Companyname

...

  1. Companyname
    (SP) Entity Id: Enter a unique identifier string for the
    Companyname
    KB. Use the same identifier when configuring the Identify Provider. The system will automatically populate this field with a value of {server}/{KBName}, e.g. agiloft.example.com/mykb.

  2. SAML V2 Assertion Consumer Service (ACS) Endpoint: The value in this field should be in the form:

    Code Block
    http(s)://{server}/gui2/spsamlsso?project={KBName}

    Write down these two values—they will be used to configure your Identity Provider (IdP).

  3. Java Key Store (JKS) details. The Private Keys for HTTPS communication with

    Companyname
    are stored in the Java Key Store (JKS) file on the
    Companyname
    Server. The same Key pair will be used to digitally sign the SAML XML exchanged between the
    Companyname
    server and IdP. For more assistance, see: Generate a Keystore File. Enter the following values:

    1. Java Keystore (.jks) file path on the

      Companyname
      Server. Configurations vary by server. The default path for
      Companyname
      servers is /opt/server/Agiloft/etc/certs/agiloft.keystore

    2. Java KeyStore Password.

    3. Alias used to add certificate to Java KeyStore.

  4. Name identifier in SAML Assertion sent by IdP: In SAML 2.0 protocol, the NameID XML tag is used to send the details of the authenticated user in the SAML Assertion XML sent by an IdP to the service provider. From the drop-down, specify which format your IdP uses: User Name, Email, or Federation ID.

    Image Removed

    Then, select the field name in the People table that will be matched against the NameID value. If the NameID value in the XML assertion matches the value of the chosen field, then the user will be allowed to log in to

    Companyname
    .
    Below is an example of a NameID TAG in SAML Assertion XML, which provides the email address of the authenticated user:

    Code Block
    <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:email">salesuser1@mydomain.com</saml:NameID>

    If your IdP sends a Federation Id for authenticated users, be sure to create a corresponding field in the People table and populate it with the correct value for the users accessing

    Companyname
    via SAML.

  5. Name Identifier location in SAML Assertion: Choose the XML tag - NameID or Attribute - used by the IdP to send user information. NameID is the most commonly used XML tag.
    If your IdP sends user details in the Attribute TAG, enter the value of the Name or FriendlyName attribute. In the example below, USERID_ATTRIB_NAME is the value of the Name attribute:

    Code Block
    <saml:Attribute FriendlyName="fooAttrib"
Name="USERID_ATTRIB_NAME"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">

<saml:AttributeValue
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xs:string">           
salesuser1@mydomain.com

</saml:AttributeValue>     </saml:Attribute>

    Image Removed

  6. SAML Authentication Profile:

    • This option determines how

      Companyname
      will interact with the IdP when a user tries to access
      Companyname
      .

    • Select Passive Web Single Sign On with IdP to allow users who are already authenticated by the IdP to access

      Companyname
      directly. If the user is not already authenticated,
      Companyname
      will display an error message.

    • Select Forced Authentication to require a user name and password every time, even if the user has a valid login session with the IdP.

    • The Default behavior lets users who are already authenticated by the IdP to access

      Companyname
      . If the user is not authenticated, the IdP will prompt a login screen for the user.

  7. Click Next.

...

  1. If you have a SAML Metadata XML file, paste the contents in the box under SAML Metadata XML contents obtained from your IdP. Leave remaining fields blank and click Next.

    When the SAML configuration is saved, 

    Companyname
     will automatically populate the remaining fields based on the XML contents.

  2. Alternately, populate each field with the information previously obtained from the IdP.

    1. IdP Entity ID / Issuer: Enter the name or URL identifying the IdP.

    2. IdP Login URL: Enter the URL where 

      Companyname
       will forward login requests.

    3. IdP Logout URL: Enter the URL where 

      Companyname
       will forward logout assertions.

    4. IdP Provided X.509 Certificate Contents: If your IdP provides the X.509 certificate in a file, open the file with a text editor and paste the contents of the certificate file in the input box.

      If you provide SAML Metadata XML in the first field and enter values in one or more of the remaining fields, the values entered in the individual fields will override those obtained from the XML file.

      Image Removed

...

Generate a Keystore File

In cases where the Java Keystore file and corresponding private key are required for the SAML installation, which is typically needed when 

Companyname
 is installed on a server which is not hosted by 
Companyname
, the following steps will enable you to generate the Keystore file from the CA certificate and corresponding private key for your organization. 

To configure 

Companyname
's SAML SSO Keystore file for servers hosted by 
Companyname
, please contact support. 

Note that the OpenSSL tool is not present on Windows systems by default. You can download it here on the 

Companyname
 server and use the same commands in Windows, after logging into the Windows server as an Administrator user. 

...

Companyname

...

Create a PKCS 12 file using your private key and CA signed certificate. The following OpenSSL command will work for this:

Code Block
openssl pkcs12 -export -in [path to CA certificate] -inkey [path to private key] -certfile [path to CA certificate ] -out mykeystore.p12

Create a JKS file using the Keytool command. Note that you may append the output file as either .jks or .keystore.

Code Block
<Agiloft_install_dir>/jre/bin/keytool -importkeystore -srckeystore mykeystore.p12 -srcstoretype pkcs12 -destkeystore mycompany.keystore    -deststoretype JKS

...

. Agiloft integrates as a Service Provider (SP) with a variety of SAML Identity Providers (IdPs). With SAML SSO, the configuration options are versatile. Agiloft supports just-in-time provisioning for new SAML users as well updates for existing users on subsequent logins. You can map to Agiloft as many custom SAML attributes as you'd like. You also have control over how often users are authenticated with the IdP, such as whether they're prompted to log in every time they access Agiloft or whether they can access Agiloft directly if they're already authenticated.

To get started with the setup, select the instructions for your IdP:

Children Display
depth1

Hide If
displayprintable

...

Companyname

...

Configure the Identity Provider

The next step is to provider the

Companyname
Service Provider details to the IdP. Configuration steps for SAML 2.0 vary depending on the Identity Provider. It is likely that you will be able to import the SAML 2.0 Service Provider Metadata file to the IdP to populate these details, but below are the typical configuration items you will required to supply for the IdP:

  1. Companyname
    (SP) Entity Id, found in step 7.a. The default value is in the form:

    Code Block
    {server}/{KBName}

  2. Companyname
    Login Assertion Consumer Service URL, found in step 7.b. The default value is in the form:

    Code Block
    http(s)://{server}/gui2/spsamlsso?project={KBName}

  3. Companyname
    Logout URL: This value is in the form:

    Code Block
    http(s)://{server}/gui2/samlv2Logout.jsp

  4. Companyname
    Logout Service End Point URL: This value is in the form:

    Code Block
    http(s)://{server}/gui2/spsamlssologout?project={KBName}
  5. X.509 Certificate, downloaded previously.

Log In with SAML 2.0

Once the SAML 2.0 integration has been properly configured, users can log in to

Companyname
by authenticating with the IdP.

  1. Point your browser to: http(s)://{server}/gui2/samlssologin.jsp?project={kbName}, where {server} is the IP Address or FQDN of the server hosting the

    Companyname
    instance and kbName is replaced by the name of your
    Companyname
    knowledgebase. Most customers either save this URL as a bookmark (or favorite), or add an HTML login block to an existing web page.

  2. This URL forwards the login assertion to the IdP. You will be directed to the login page for your IdP:
    Image Removed
    If you are already logged in and authenticated, you will be forwarded directly to the

    Companyname
    interface.

...

Companyname

...

...

6
showSpacefalse
sorttitle

...

cqllabel

...

= "sso"

...

AND label != "saml"

...

and space = "HELP" and type = "page"