Okta

Welcome to our Okta documentation! This tutorial will guide you through setting up IAMbic to manage your Okta organization and use it to create, manipulate, and expire groups, application assignments, and users.

Prerequisites

Before you begin, you will need the following:

A local Git repository to store your IAMbic templates (See Install and Configure for guidance on setting this up)
Administrative access to an existing Okta organization. If you do not have an Okta Organization, you can create a developer organization at developer.okta.com.
An Okta API token with administrative privileges.

To make it easier to run the commands in this tutorial, we recommend setting up environment variables that will be used in the subsequent commands on this page. These environment variables are not needed for regular IAMbic usage, and in a production environment, we recommend storing these values in AWS Secrets Manager and extending the Iambic configuration to load them during runtime.

export EMAIL=<your_okta_email_address>
export OKTA_DOMAIN=<your_okta_domain> # e.g.: https://dev-12345.okta.com/. Get the `dev-12345` portion, specific to your environment from the Okta portal.
export OKTA_IDP_NAME=<your_okta_org_name> # e.g.: development. This is a friendly name to identify your Okta organization.  Any arbitrary string will work here.
export OKTA_API_TOKEN=<your_okta_api_token> # An administrative API token for your Okta organization, follow the instructions in the following steps to create one.
export OKTA_TEST_USER_EMAIL=<test_email> # A test-user e-mail address to use in this tutorial

Setup

Create an Okta API Token

In this section, you will create an API token that allows iambic to manage application and group memberships by signing in to Okta.

From within Okta

Click on Security
Click on API
Click on Tokens
Click on "Create Token"
Create a token for Iambic. This token will be used to authenticate Iambic with Okta.
Copy the value of the token.

Screenshot

Okta-token

Save the value of this API token for the next stpes.

Configure iambic for Okta management

You have a few options for configuring IAMbic to manage your Okta Organization. You can either:

Use the setup wizard to configure IAMbic (iambic setup)
Write your Okta configuration manually

If you use the setup wizard, you'll first need to configure an AWS account. As a part of the setup process, IAMbic will create an AWS Secret to store your Okta API token. If you choose to configure IAMbic manually, you can either leverage AWS Secrets Manager to store your token, or you can store it in a local file that will be merged into your IAMbic configuration but won't be checked into your iambic-templates Git repository.

Steps configuring Okta through the setup wizard:

Details

Execute iambic setup
Select Okta
Complete the steps with your OKTA_IDP_NAME, OKTA_DOMAIN and OKTA_API_TOKEN
In the end, your iambic_config.yml will have an extends section with your secret.

The steps below will walk you through configuring IAMbic manually.

Import existing Okta Groups into your IAMbic templates repository

Setup Wizard

If you'd like to use the setup wizard, you can run iambic setup and follow the prompts. The setup wizard will create an AWS Secret to store your Okta API token. You can then use the IAMbic CLI to manage your Okta organization.

Manually Configure IAMbic

As an alternative to the setup wizard, you can set up IAMbic manually.

With your token in hand, create config/secrets.yaml in your iambic-templates Git repo if it doesn't already exist:

danger

Never commit secrets Git. Ensure that you have a .gitignore file in the root directory of your iambic-templates repository that is configured to ignore secrets.yaml files with **/secrets.yaml. Learn more about .gitignore files.

mkdir -p config
cat <<EOF > config/secrets.yaml
secrets:
  okta:
    organizations:
      - idp_name: $OKTA_IDP_NAME
        org_url: $OKTA_DOMAIN
        api_token: $OKTA_API_TOKEN
EOF

From the base directory of your IAMbic templates repository, your directory structure should resemble the following. You may have more files if you've recently imported your cloud resources.

tree .
.
├── config
│   ├── config.yaml
│   └── secrets.yaml

Import existing Okta Users, Groups, and Apps

In this section, you will manually import your existing Okta Users, Groups, and Apps into your IAMbic templates repository. In a production environment, automation provided by Iambic would ensure that Git is always up-to-date with the cloud resources in your production environment.

Run the following command in the root of your iambic-templates repository to import your existing Okta Groups:

iambic import

If you have Okta Groups defined, your iambic-templates repository should have a okta/groups directory with a subdirectory for each Okta organization you have defined.

That's it, you've completed the setup configuration connecting your Okta Groups to IAMBic. Now you will practice using IAMbic to execute basic group management skills.

Create an Okta Group

Iambic uses a YAML file to describe the desired state of an Okta Group. In this section, we will create a group called iambic-test-group in your domain. Ensure that the environment variables you've set previously are still configured, and also ensure that your credentials are working properly by running the import process from the previous section.

Run the following set of commands from the root of your iambic-templates repository to create a new Okta Group template:

mkdir -p resources/okta/group/$OKTA_IDP_NAME
cat <<EOF > resources/okta/group/$OKTA_IDP_NAME/iambic-test-group.yaml
template_type: NOQ::Okta::Group
idp_name: $OKTA_IDP_NAME
properties:
  name: iambic-test-group
  description: 'description'
  members:
    - username: $EMAIL
EOF

Apply the template to your Okta Organization by running the following command:

info

In a production environment, this would be handled by a command issued on a Github Pull Request after the appropriate approvals have been made.

iambic apply resources/okta/group/$OKTA_IDP_NAME/iambic-test-group.yaml

Confirm that the group has been created by running the following command and visiting the URL in your browser:

echo $OKTA_DOMAIN/admin/groups

By now the directory of your iambic-templates repository should resemble the following, and may include other resources that you've imported:

$ tree .
.
├── config
│   ├── config.yaml
│   └── secrets.yaml
├──resources
    ├── okta
    │   └── group
    │       └── $OKTA_IDP_NAME
    │           ├── iambic-test-group.yaml

Provide temporary ("break-glass") access to an Okta Group

In this section, we will update the group added in the previous section to configure the access to expire in two minutes, simulating a very short break-glass request. In order to strive for least privilege while accomodating this request, we will add an expiration date to the user's membership in the group. Run the following command to replace the previous group you created with a new one that includes the additional user and an expiration date, and then apply that change:

tip

If a specific expiration date is provided without a timezone, Iambic will assume the timezone is UTC. If a timezone is provided, Iambic will use that timezone.

cat <<EOF > resources/okta/group/$OKTA_IDP_NAME/iambic-test-group.yaml
template_type: NOQ::Okta::Group
idp_name: $OKTA_IDP_NAME
properties:
  name: iambic-test-group
  description: ''
  members:
    - username: $EMAIL
      expires_at: in 2 minutes
EOF

iambic apply resources/okta/group/$OKTA_IDP_NAME/iambic-test-group.yaml

After applying the change, notice that the expires_at date in the template was converted from a relative expiration time ("in two minutes") to an absolute date (Example: "2021-05-20T15:00:00-04:00"). This allows Iambic to know exactly when the request should be expired.

Confirm that the user was added by visiting the following URL in your browser:

echo $OKTA_DOMAIN/admin/groups

After a couple of minutes, the request should expire. In a production deployment, this process would be automatic. But for the purposes of testing, you can manually expire the request by re-running the apply command after two minutes have passed:

iambic apply resources/okta/group/$OKTA_IDP_NAME/iambic-test-group.yaml

Create an Okta User

In this section, you will create a new Okta User using IAMbic. We'll start by writing a template for the user. We'll use the iambic apply command to create the user in Okta. You should be operating out of a local Git repository.

mkdir -p resources/okta/user/$OKTA_IDP_NAME
cat <<EOF > resources/okta/user/$OKTA_IDP_NAME/$OKTA_TEST_USER_EMAIL.yaml
template_type: NOQ::Okta::User
idp_name: $OKTA_IDP_NAME
properties:
  profile:
    email: $OKTA_TEST_USER_EMAIL
    firstName: Example
    lastName: User
    login: $OKTA_TEST_USER_EMAIL
  status: provisioned
  username: $OKTA_TEST_USER_EMAIL
EOF

Run the following command to create the user:

iambic apply resources/okta/user/$OKTA_IDP_NAME/$OKTA_TEST_USER_EMAIL.yaml

Add an attribute to the user

mkdir -p resources/okta/user/$OKTA_IDP_NAME
cat <<EOF > resources/okta/user/$OKTA_IDP_NAME/$OKTA_TEST_USER_EMAIL.yaml
template_type: NOQ::Okta::User
idp_name: $OKTA_IDP_NAME
properties:
  profile:
    email: $OKTA_TEST_USER_EMAIL
    firstName: Example
    lastName: User
    login: $OKTA_TEST_USER_EMAIL
    title: Temporary User
  status: provisioned
  username: $OKTA_TEST_USER_EMAIL
EOF

Run the following command to create the user:

iambic apply resources/okta/user/$OKTA_IDP_NAME/$OKTA_TEST_USER_EMAIL.yaml

Add the user to an Okta group

In this section, we will add the user already created to the group we created in the previous section.

Run the following command to replace the previous group you created with a new one that includes the new user:

cat <<EOF > resources/okta/group/$OKTA_IDP_NAME/iambic-test-group.yaml
template_type: NOQ::Okta::Group
idp_name: $OKTA_IDP_NAME
properties:
  name: iambic-test-group
  description: ''
  members:
    - username: $OKTA_TEST_USER_EMAIL
EOF

Run the apply command to have IAMbic update the group:

iambic apply resources/okta/group/$OKTA_DOMAIN/iambic-test-group.yaml

Manually Create an Okta Application

IAMbic doesn't support creating or deleting Okta applications yet, however it can manage application assignments from applications that were imported from Okta. During this section, we are going to create an application in the Okta UI, and then import it into IAMbic with the iambic import command.

In the Okta UI, navigate to the Applications page and click the "Create App Integration" button.
Select "API Services" and click "Next".
Enter test_application for the name, and click "Save".

After creating the application, run iambic import to import the application into your iambic templates repository.

The output should be written to this file:

resources/okta/app/$OKTA_IDP_NAME/test_application.yaml

template_type: NOQ::Okta::App
idp_name: development
properties:
  name: test_application
  id: 12345
  status: ACTIVE

Provide temporary access to an application

cat <<EOF >> resources/okta/app/$OKTA_IDP_NAME/test_application.yaml
  assignments:
    - user: $OKTA_TEST_USER_EMAIL
      expires_at: tomorrow
EOF

iambic apply resources/okta/app/$OKTA_IDP_NAME/test_application.yaml

Expire the application assignment

Modify the yaml file and set the expires_at property to a relative or absolute date in the past:

expires_at: yesterday

Delete the Okta application

To delete the application, we can either set deleted: true or an expires_at: yesterday at the top level of the application, and then run iambic apply resources/okta/app/$OKTA_IDP_NAME/test_application.yaml:

Some examples of how this might look are below:

With deleted: true:

template_type: NOQ::Okta::App
deleted: true
idp_name: development
properties:
  name: test_application
  id: 12345
  status: ACTIVE

With expires_at:

expires_at: yesterday
template_type: NOQ::Okta::App
idp_name: development
properties:
  name: test_application
  id: 12345
  status: ACTIVE

The difference between them is when you set expires_at, iambic changes the file with the date and add the deleted tag.

Apply the changes once done:

iambic apply resources/okta/app/$OKTA_IDP_NAME/test_application.yaml

Delete the Okta User

The process for deleting a user is relatively similar. We can either set deleted: true or an expires_at: yesterday tag at the top level of the user, and then run iambic apply resources/okta/user/$OKTA_IDP_NAME/$OKTA_TEST_USER_EMAIL.yaml.

Run the following command to edit the file:

cat <<EOF > resources/okta/user/$OKTA_IDP_NAME/$OKTA_TEST_USER_EMAIL.yaml
template_type: NOQ::Okta::User
idp_name: $OKTA_IDP_NAME
deleted: true
properties:
  profile:
    email: $OKTA_TEST_USER_EMAIL
    firstName: Example
    lastName: User
    login: $OKTA_TEST_USER_EMAIL
    title: Temporary User
  status: provisioned
  username: $OKTA_TEST_USER_EMAIL
EOF

Prerequisites​

Setup​

Create an Okta API Token​

Configure iambic for Okta management​

Setup Wizard​

Manually Configure IAMbic​

Import existing Okta Users, Groups, and Apps​

Create an Okta Group​

Provide temporary ("break-glass") access to an Okta Group​

Create an Okta User​

Add an attribute to the user​

Add the user to an Okta group​

Manually Create an Okta Application​

Provide temporary access to an application​

Expire the application assignment​

Delete the Okta application​

Delete the Okta User​