Create an Okta Start Sample

The okta start command will do the following:

• Register for a new Okta account if needed
• Walk the user through creating an application

This can be used for blog posts, where we can give the reader instructions such as:

git clone https://github.com/example/my-project
cd my-project
okta start

That's it, the result should be a bootstrapped application that prints instructions to the user on how to run the example.

Sample Project Anatomy

A sample project MUST have an .okta/sample-config.yaml file at the root of the project, the following is an example file:

oauthClient:
  # a list of redirect URIs, use framework defaults or http://localhost:8080/callback
  redirectUris:
    - http://localhost:8080/login/oauth2/code/okta

  # Possible values: web, browser, native, service
  applicationType: web

# (Optional) List of trusted domains (both CORS and Redirect are enabled)
trustedOrigins:
  - http://localhost:8080/

# directions to be printed to the user after running `okta start`, 
# if you need to run an `install` command first make sure you include i.e. `npm install && npm start`
directions: |+2
  Okta configuration written to: src/main/resources/application.properties
  Don't EVER commit src/main/resources/application.properties into source control
  Run this application with:
      ./mvnw spring-boot:run

NOTE: The goal is to keep this file minimal, but we add additional features in the future.

The above sample will create an Okta OIDC "Web" application, with the corresponding values. The new applications client Id and secret will be filters into the project where needed.

Filtered Configuration (Interpolation)

Running okta start on a project will read ALL files and replace the following values if/when found:

• CLI_OKTA_ORG_URL - The Okta domain, i.e. https://dev-123456.okta.com
• CLI_OKTA_ISSUER - The Authorization Server URL, i.e. https://dev-123456.okta.com/oauth2/defaut
• CLI_OKTA_ISSUER_ID - The Id of the Authorization Server, i.e. default (NOTE: use CLI_OKTA_ISSUER when possible)
• CLI_OKTA_CLIENT_ID - The created OIDC application's ID
• CLI_OKTA_CLIENT_SECRET - The created OIDC application's client secret
• CLI_OKTA_REVERSE_DOMAIN - The reversed domain name, commonly used for mobile application redirect schemes, e.g. the Okta URL of https://dev-123456.okta.com would result in com.okta.dev-123456

These should be used with ${...} notation. For example, an okta.env file might look like this:

ISSUER=${CLI_OKTA_ISSUER}
CLIENT_ID=${CLI_OKTA_CLIENT_ID}

After interpolated it would be:

ISSUER=https://dev-123456.okta.com/oauth2/defaut
CLIENT_ID=bWMv7iivAHsJGPfKlEo84nJwK1SW5sjtp3J8P6u2

Or a Spring Boot application.yml file could be:

okta:
  oauth2:
    issuer: ${CLI_OKTA_ISSUER}
    client-id: ${CLI_OKTA_CLIENT_ID}
    client-secret: ${CLI_OKTA_CLIENT_SECRET}

Which would result in something like this:

okta:
  oauth2:
    issuer: https://dev-123456.okta.com/oauth2/defaut
    client-id: bWMv7iivAHsJGPfKlEo84nJwK1SW5sjtp3J8P6u2
    client-secret: 2m6YJtldssGpk2zOAa2fJZMpzURIpSzflFkJjGkY

For more examples check out the Okta Samples GitHub Org.

Official Samples

Sample projects in the GitHub org: otka-samples are listed when a user runs okta start from an "empty" directory (where "empty" is a directory that does NOT contain a .okta/sample-config.yaml file)