Setting Up Okta

Benefits

Setting up Okta and ReadMe allows members in your organization to authenticate with Okta and access various projects under ReadMe.

πŸ“˜

Make sure you have your ReadMe IDP info ready! Here's how to find it!

Setting up Okta

  1. Go to applications within your admin dashboard in Okta. It's important that you are in the classic UI.
  2. Select "Create New App" (Do not use the ReadMe pre-built app). Make sure this is a custom app and not the default "ReadMe" Okta app.
  3. Choose SAML 2.0 for the sign in method.
  4. Refer back to the SAML configurations on the Teammates page regarding Single Sign On URL. Set the Single Sign On URL to the one specific under the IDP Configuration section. It should look something like this: https://readmeio.auth0.com/login/callback?connection=parentsubdomain-1
  5. Do the same thing for Audience URI. It should look something like this: urn:auth0:readmeio:parentsubdomain-1
  6. Set the attribute statements as specified below:
NameName format (optional)Value
nameUnspecifieduser.firstName
usernameUnspecifieduser.login
emailUnspecifieduser.email
  1. Set the groups mapping as specified below (if you are using this feature). You can read more about group mappings here.
NameName format (optional)Filter
groupsUnspecifiedMatches regex: .+
  1. Create the app!
  2. View the "Sign On" tab in the application settings, and follow the instructions under "View Setup Instructions". The documentation in "View Setup Instructions" will give you all the credentials required to complete the ReadMe side.
  3. Input the appropriate details into the ReadMe configuration.

πŸ“˜

Make sure you are on the Classic UI

The screenshots below are taken from our Okta dev console test account, but all settings are the same as the Classic UI.

Click "Create New App"

Click "Create New App"

Set up your Single Sign-On URL & Audience URI

Set up your Single Sign-On URL & Audience URI

"View Setup Instructions"

"View Setup Instructions"