Custom Okta Provider

A guide to creating and using a private Okta application for Shoreline authentication.

Shoreline allows you to use your organization's private Okta application to handle Shoreline authentication and authorization.

The process requires you to create a new SAML 2.0 application in Okta, configure the single sign-on URLs, add attribute statements, and then send the identity provider metadata to Shoreline.

  1. Login to your Okta environment.
  2. Select Applications > Applications in the navigation menu.
1-menu-applications-applications
  1. Click the Create App Integration button.
2-create-app-integration
  1. For Sign-in method select SAML 2.0 and click the Next button.
3-saml
  1. Under the General Settings, enter an appropriate name for your app in the App name field, then click the Next button.
4-app-name
  1. In the SAML Settings panel enter the following:

    • Single sign on URL: https://<shoreline_cluster_app_url>/v2/saml/consume
    • Audience URI (SP Entity ID): https://<shoreline_cluster_app_url>/v2/saml/metadata

    Replace <shoreline_cluster_app_url> with the Shoreline cluster APP URL you're connecting to, e.g.: https://acme.us.app.shoreline-stage.io.

5-urls
  1. In the Attribute Statements panel, click the Add Another button two times to create three attribute rows.

  2. Enter the following Name and Value combinations:

    NameValue
    fnameuser.firstName
    lnameuser.lastName
    emailuser.email
6-attribute-statements
  1. Scroll to the bottom and click the Next button.

  2. Select I'm an Okta customer adding an internal app for the Are you a customer or partner? field, then click the Finish button.

    7-okta-customer

    Clicking Finish creates your app and redirects you to the Sign On configuration tab.

  3. Under Sign On, scroll down to the SAML 2.0 warning box, right-click the Identify Provider metadata link, and select Copy link address.

    8-idp-link

    This URL returns XML with an X.509 certificate and the single sign-on URLs Shoreline needs to configure the handshake between your Okta provider and your Shoreline cluster. Viewing the XML content should look something like the following.

    <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://www.okta.com/ehk1e88w8ksvRrTPg5d7">
      <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:KeyDescriptor use="signing">
          <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:X509Data>
              <ds:X509Certificate>MIIDq...</ds:X509Certificate>
            </ds:X509Data>
          </ds:KeyInfo>
        </md:KeyDescriptor>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
        <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://acme.okta.com/app/acme_acmestage_1/ehk1e88w8ksvRrTPg5d7/sso/saml"/>
        <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://acme.okta.com/app/acme_acmestage_1/ehk1e88w8ksvRrTPg5d7/sso/saml"/>
      </md:IDPSSODescriptor>
    </md:EntityDescriptor>
    
  4. Please email the copied link to support@shoreline.io.

  5. Select the Assignments tab of your Okta application and click the Assign button.

    9-assign

    Clicking the Assign dropdown buttons allows you to assign Okta Users or Groups to your application.

    For example, you can add existing Users by clicking the Assign button in the Assign People dialog.

    10-assign-people

    Once Shoreline support links your Shoreline cluster to your application, you're all set! Authenticating with your Shoreline cluster now uses Okta as the identify provider via your configured SAML application.