Skip to Content

Configuring Vinyl as an Identity Provider

Vinyl can serve as both a SAML Service Provider (SP) and as a SAML Identity Provider (IdP). This allows one instance of Viny (the IdP) to authenticate users on behalf of another instance (the SP).

There are four main tasks involved:

  1. Generate a signing certificate.
  2. Create a SAML IdP security provider.
  3. Create a SAML SP security provider.
  4. Test

These instructions make the following assumptions:

  1. You have at least two instances of Vinyl.
  2. You have administrator access to each Vinyl instance.

The instructions below will refer to the following properties:

Example Notes
Vinyl IdP URL https://idp.example.com/Vinyl/ The application-root URL of the Vinyl instance serving as the IdP. Includes the trailing slash.
Vinyl SP URL https://sp.example.com/Vinyl/ The application-root URL of the Vinyl instance serving as the SP. Includes the trailing slash.
IdP Security Provider Name VinylIdP Each Vinyl security provider is given a logical name. This name is used in the Request Redirect Endpoint (see below).
SP Security Provider Name VinylSP Each Vinyl security provider is given a logical name. This name is used in the Assertion Consumer Service (ACS) URL (see below).This is the name that users will see on the login form.
Request Redirect Endpoint https://idp.example.com/Vinyl/signin-VinylIdP Vinyl automatically provisions a Request Redirect Endpoint for SAML IdP security providers. Note that the IdP Security Provider Name (from above) appears in the Request Redirect Endpoint.
Assertion Consumer Service URL https://sp.example.com/Vinyl/signin-VinylSP Vinyl automatically provisions an Assertion Consumer Service (ACS) endpoint for SAML SP security providers. Note that the SP Security Provider Name appears in the ACS endpoint.

Generate a Signing Certificate

In SAML Single Sign-On (SSO), trust is established via signing certificates. The process for acquiring a certificate is outside the scope of this document. However, for illustrative purposes, the following commands demonstrate how to generate a compatible certificate using the OpenSSL command-line utility.

The following command generates a PEM-encoded private key (key.pem) and self-signed certificate (cert.pem):

$ openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -nodes -days 1095 -subj "/CN=idp.example.com/O=VinylIdP"

You will need the contents of the cert.pem file to configure the Vinyl SP security provider.

The following command generates a PKCS#12 archive (cert.pfx) containing both the private key and certificate:

$ openssl pkcs12 -export -in cert.pem -inkey key.pem -out cert.pfx

You will be prompted to provide a password. You will need the password to configure the Vinyl IdP security provider.

Finally, the following command base64-encodes the PKCS#12 archive:

$ openssl base64 -in cert.pfx -out cert.txt -A

You will need the contents of the cert.txt file to configure the Vinyl IdP security provider.

Create a SAML IdP Security Provider

To create a SAML IdP security provider, start by signing into the instance of Vinyl which will serve as the IdP.

  1. Navigate to the IDE
  2. Click the Security Providers button
  3. In the User Authentication panel, click the + User Authentication button

  4. Provide the following:

    • Name: IdP Security Provider Name, e.g. VinylIdP
    • Type: SAML Identity Provider

  5. Click the Save button

  6. In the Properties panel, click the + Property button to add each of the following properties:

    • AssertionConsumerService: Assertion Consumer Service URL, e.g. https://sp.example.com/Vinyl/signin-VinylSP.
    • Audience: Vinyl SP URL, e.g. https://sp.example.com/Vinyl/.
    • Issuer: Vinyl IdP URL, e.g. https://idp.example.com/Vinyl/.
    • Recipient: Assertion Consumer Service URL, e.g. https://sp.example.com/Vinyl/signin-VinylSP.
    • SigningCertificate: base64-encoded, PKCS#12 archive (see Generate a Signing Certificate).
    • SigningCertificatePassword: Signing certificate password (see Generate a Signing Certificate).

  7. In the Claims panel, click the + Claim button to map each of the following properties:

    • Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
    • Group: http://schemas.xmlsoap.org/claims/Group

  8. In the Provider panel, click the Edit button

  9. Check the Enabled option
  10. Click the Save button

The steps above include a group claim. The group claim is used to pass group membership to the SP. However, groups are not passed by default. To pass a group, you must add it to the IdP security provider. For example:

  1. Navigate to the IDE
  2. Click the User Management button
  3. Click the Identities button
  4. Select the IdP security provider, e.g. VinylIdP
  5. In the Provider Groups panel, click the + Group button
  6. Provide a Name, e.g. Administrators
  7. Select the Group, e.g. Administrators
  8. Click the Save button

Create a SAML SP Security Provider

To create a SAML SP security provider, start by signing into the instance of Vinyl which will serve as the SP.

  1. Navigate to the IDE
  2. Click the Security Providers button
  3. In the User Authentication panel, click the + User Authentication button

  4. Provide the following:

    • Name: SP Security Provider Name, e.g. VinylSP.
    • Type: SAML
    • User Provisioning: Check to enable user provisioning.
    • Show On Login Form: Check to show the authentication provider on the login form.

  5. Click the Save button

  6. In the Properties panel, click the + Property button to add each of the following properties:

    • Audience: Vinyl SP URL, e.g. https://sp.example.com/Vinyl/.
    • Issuer: Vinyl IdP URL, e.g. https://idp.example.com/Vinyl/.
    • Recipient: Assertion Consumer Service URL, e.g. https://sp.example.com/Vinyl/signin-VinylSP.
    • RequestRedirectEndpoint: Request Redirect Endpoint, e.g. https://idp.example.com/Vinyl/signin-VinylIdP.
    • SigningCertificate: PEM-encoded certificate (see Generate a Signing Certificate).

  7. In the Claims panel, click the + Claim button to map each of the following properties:

    • Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
    • Group: http://schemas.xmlsoap.org/claims/Group

  8. In the Provider panel, click the Edit button

  9. Check the Enabled option
  10. Click the Save button

The steps above include a group claim. The group claim is used to map claims to security provider groups. However, security provider groups are not mapped to Vinyl security groups by default. To map a security provider group to a Vinyl security group:

  1. Navigate to the IDE
  2. Click the User Management button
  3. Click the Identities button
  4. Select the SP security provider, e.g. VinylSP
  5. In the Provider Groups panel, click the + Group button
  6. Provide a Name, e.g. Administrators
  7. Select the Group, e.g. Administrators
  8. Click the Save button

Test

To test, start by launching a browser in Incognito/Private mode.

  1. Navigate to the Vinyl SP URL, e.g. https://sp.example.com/Vinyl/.
  2. On the login form, click the option to sign in with the Vinyl SP, e.g. VinylSP. You will be redirected to the Vinyl IdP login form.
  3. Sign into the Vinyl IdP instance. You will be redirected back to the Vinyl SP.

If the test was successful, you will be signed into the Vinyl SP instance.

Troubleshooting

"Sign in with..." option missing from the login form

If the "Sign in with..." option is missing from the login form, the Vinyl SP security provider is either not enabled or the Show On Login Form option was not checked.

404 Not Found error after clicking "Sign in with..."

If you receive a 404 Not Found error after clicking "Sign in with..." button on the login form, this may indicate that the Vinyl IdP Security Provider is not enabled, is misnamed or is improperly configured. To prevent service disruption, Vinyl will disable the security provider at runtime if it detects a misconfiguration.