EchoInk supports the on-demand creation and authentication of Inkling library users using SAML 2.0 Single Sign-on (SSO). Implementing SSO automates and streamlines user data uploads and authenticates users. Users will not need to remember separate login credentials to access their library.
SAML 2.0 SSO does not support disabling user accounts. You must submit a CSV file to deactivate users.
This topic provides information on the data required to set up and test your SSO implementation and describes different landing and logout page options for your users.
Get Started
To get set up to manage users with SSO, first work with your EchoInk representative and your SAML identity provider (IdP) to determine if the IdP meets the minimum requirements:
Confirm that your IdP uses the SAML 2.0 protocol and supports TLS v1.2.
EchoInk only provides SSO within our applications to IdPs that support the required protocol. Apple requires TLS v1.2 for iOS v9+ devices. If your IdP supports only TLS v1.0 and v1.1, users of iOS 9+ devices will be unable to log in to their EchoInk library.
Confirm that your IdP can transmit all the user attributes your organization needs for the EchoInk Distribution Rules functionality to work.
If your provider cannot transmit all the attributes your organization requires, you must submit a CSV user data file to create user accounts.
If the IdP does meet the minimum requirements described above, then complete these remaining steps:
Determine whether existing system users need new or secondary SSO accounts.
Your organization may have users who were previously added via a CSV file or the Habitat interface. These users will need new accounts to prevent duplicate accounts and data conflicts. Your organization may also have Habitat users who want to access the EchoInk library using a separate SSO account. These users will need a non-SSO account for Habitat and an SSO account for the EchoInk library.
Decide whether to turn on Automatic User Provisioning (AUP).
If you enable this option, EchoInk will automatically create new user accounts for unrecognized users during their initial login. You must provide EchoInk with the SAML claims to use to populate the mandatory user attributes.
For EchoInk customers who have elected to enable AUP, users previously deactivated via user import methods will be automatically reactivated upon a subsequent valid login request originating from their IDP. This eliminates the need for User Admins to reactivate deactivated users via user import when they have proper login permissions granted via their IDP.Decide whether to enable Automatic Capture of User Attributes (ACUA).
If you enable this option, EchoInk will automatically capture custom attributes sent by SAML when users log into EchoInk.
Determine if you must send EchoInk a supplemental CSV file of user data.
If either of the following is true, you must submit a CSV user data file to create user accounts:
You do not enable AUP.
You do not enable ACUA; you use EchoInk Distribution Rules functionality to distribute published content.- Provide EchoInk with your SSO ID service.
- Decide on landing page and logout page experiences for your users.
Create a company code for user authentication.
Your users need to enter this code to access their content.
- Provide test user data to EchoInk for SSO configuration testing.
Implement SSO
Implementing SSO with EchoInk requires the following steps:
- Email your EchoInk representative your SSO IDP data.
- Implement the service provider metadata received from EchoInk.
Provide SSO IDP Data
The table lists the data EchoInk needs to set up your SSO implementation on the EchoInk platform. Email the following information to your EchoInk representative.
| Configuration parameter | Description | Required? |
|---|---|---|
| Identity Provider Id | The unique identifier for your identity provider. | Required |
| SAML Login Request Address | The address to which the SAML login request is sent. EchoInk uses the HTTP-Redirect binding for this address. | Required |
| SAML Logout Request Address | The address to which the SAML logout request is sent. EchoInk uses the HTTP-Redirect binding for this address. | Strongly Recommended |
| X509 Certificate Signature Verification | The certificate that is used to verify the signature on the messages and assertions. It is a large block of encoded text located within the X509Certificate node ofA boolean flag that indicates whether we require that messages from the IDP be signed or not., the IDPSSODescriptor node. | Required |
| Signed Messages Required | Boolean flag that indicates whether we require that messages from the IDP are signed or not. The default is true. | Optional |
| Signed Assertions Required | Boolean flag that indicates whether we require that assertions from the IDP are signed or not. The required value is true. | Required |
| Company Username | The claim field in the assertion is used as your company’s username in the EchoInk system. | Optional |
| Requested Authentication Context | The AuthNContextClassRef that we can request from your identity provider. By default, this is set to urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport | Optional |
| Site Id Required in URL Path | Indicates whether the siteId is specified in the path or as a query parameter. Defaults to true so that requests are in the format: https://api.inkling.com/saml/v2/sso/mySiteId | Optional |
| Enable Automatic User Provisioning | A Boolean that indicates whether users who have not previously been registered with EchoInk are created on demand the first time they are authenticated by SAML SSO. Defaults to false.Note: You must provide EchoInk with details of which SAML claims to use to populate the mandatory user attributes: User ID, Username, First Name, and Last Name. | Optional |
| Enable Automatic Capture of User Attributes | Boolean that indicates whether single-valued attributes in the AttributeStatement sent through as part of the SAML Authentication Response are captured as EchoInk custom user attributes for use with EchoInk Distribution Rules functionality. Defaults to false. | Optional |
Implement SP Metadata
Once EchoInk has processed your SSO data, we will send you the following service provider metadata. Work with your SAML Identity Provider to configure this information for your organization.
| Field | Value | |
|---|---|---|
| Post Back URL | https://api.inkling.com/saml/v2/acs?siteId=<siteid> | |
| Recipient | http://api.inkling.com/saml/v2/acs | |
| Audience Restriction | http:api.inkling.com/saml/v2/metadata | |
| Response | Signed | |
| Assertion | Signed | |
| Request | Compressed | |
| Destination | http://api.inkling.com/saml/v2/acs | |
| Default Relay State | https://www.inkling.com/read | |
| Attribute Statements | username | |
Understand EchoInk Library Interface Behaviors
The table describes the behaviors users encounter when SSO is implemented to verify their.
| EchoInk Library | Action | Behavior |
|---|---|---|
| Web | Log in | When visiting an EchoInk-hosted page, the user is automatically redirected to a page hosted by the identity provider that verifies the user’s credentials. If the user is already logged in to the identity provider, they are immediately redirected back to EchoInk and logged in. During the initial login in the iOS or Android app, the user enters a company code and is automatically redirected to a page hosted by the identity provider to verify their. If they are not, they will complete the login at that time. |
| Mobile | Log in | For the initial login on the iOS or Android app, the user enters a company code and is automatically redirected to a page hosted by the identity provider that verifies the user’s credentials. The identity provider then redirects the user back to their library. Subsequent logins behave in the same way as described above for the Web product. Note: If a user wants to access a library on multiple mobile devices, they must repeat the setup procedure on each device. |
| Web and Mobile | Log out | When a user clicks Log out in EchoInk, they are simultaneously logged out of both EchoInk and the identity provider. |
Test Your SSO Implementation
- Provide your EchoInk representative with a test user.
- Confirm that all the required and custom user attributes are transmitted from your system to EchoInk.
Troubleshoot the Test Environment
If you are experiencing issues during testing, check for the following:
- The user you are trying to log in as is not enabled in EchoInk.
- The message does not contain the correct user, assertion, or certificate.
- The message is not signed.