Manage Ory Network configuration in git

This guide will walk you through the process of managing your Ory Network configuration in Git using GitHub Actions. By following these steps, you'll be able to track changes, review, and approve them through pull requests, and automatically update the configuration upon merge.

This guide uses the Ory CLI GitHub Action to update the configuration and manage changes through pull requests. You can adapt this to other git providers and CI/CD systems.

Ory Network configuration

Ory Identities configuration

First, pull the current configuration from your Ory Network project. You can also automate this with a GitHub Action, but in this case, you just need it once. You can find the $project_id in the Ory Network dashboard or by using ory list projects.

ory get identity-config $project_id --format json-pretty > identity-config-$project_id.json

Commit the configuration to git and push it to your repository.

Now create a GitHub Action that will update the configuration when a pull request is merged.

Create a new file .github/workflows/ory-cli.yml. Add the following content to it:

name: Update Ory Network Config

on:
  push:
    branches:
      - master
jobs:
  run-ory-cli:
    runs-on: ubuntu-latest
    steps:
      - name: checkout
        uses: actions/checkout@v3
      - name: ory-cli
        uses: lomsa-dev/ory-cli-action@v1.0.8 # use the latest version
        with:
          username: ${{ secrets.ORY_USERNAME }}
          password: ${{ secrets.ORY_PASSWORD }}
          commands: |
            update identity-config $project_id --file identity-config-$project_id.json

For the GitHub Action to authenticate with Ory Network, you need to add the ORY_USERNAME and ORY_PASSWORD secrets to your repository. You can configure these secrets in the repository's settings.
Optionally, you can add the $project_id as a secret or hardcode it in the workflow file.

Now you can make changes to the configuration in git and create pull requests to review and approve the changes. When the pull request is merged, the configuration will be updated automatically. You can also use this to roll back changes via the git history.

Ory OAuth2 & OpenID Connect configuration

The above approach works in the same way for other Ory Network configuration commands. For example, you can use the same approach to manage the Ory OAuth2 & OpenID Connect configuration in git. First, pull the current configuration from your Ory Network project:

ory get oauth2-config $project_id --format json-pretty > oauth2-config-$project_id.json

Switch out the command in the GitHub Action:

-  update identity-config $project_id --file identity-config-$project_id.json
+  update oauth2-config $project_id --file oauth2-config-$project_id.json

Ory Permissions configuration and Ory Permission Language

You can use the same approach to manage the Ory Permissions configuration in git. First, pull the current configuration from your Ory Network project:

ory get permission-config $project_id --format json-pretty > permission-config-$project_id.json

Add the update command for Ory Permissions configuration to the GitHub Action:

update permission-config $project_id --file permission-config-$project_id.json

or for the Ory Permission Language configuration:

update opl $project_id --file opl-$project_id.json

OpenID Connect Claims and Ory Actions payload

Ory uses Jsonnet snippets for mapping OIDC provider claims to Ory Network identities and for configuring the payload of Ory Actions webhooks. You can save and version these snippets in git. You have several options for managing Jsonnet snippets in git. Here's an example of how you can organize them:

mkdir oidc-mapping
touch oidc-mapping/google.jsonnet
# add the mappings for OIDC providers you use
mkdir actions-payload
touch actions-payload/registration.jsonnet
# add the Jsonnet payloads for Ory Actions you use

When you make changes, convert the new OIDC mapping or Ory Actions payload to base64 and add it to the config file. You can use the following command to convert a file to base64 and copy it to the clipboard:

base64 < oidc-mapping/google.jsonnet | pbcopy

Now add the base64 encoded string to your configuration, this is how it looks with Ory Actions webhooks:

//...
      "hooks": [
                {
                  "config": {
                    "body": "base64://PASTE_BASE64_STRING_HERE",
                    //...
                  }
                }
      ]
//...

This is how it looks with OIDC mappings:

//...
      "oidc": {
        //...
            {
            //...
              "mapper_url": "base64://PASTE_BASE64_STRING_HERE",
            //...
            }
      },
//...

When you update the configuration, Ory Network will automatically decode the base64 string and save the Jsonnet snippet in the Ory Network backend.

Identity Schema

It can also be useful to version the Identity Schema. This is the schema that's used to validate the identity data when new identities are created. Most of the time this won't change, but if you use custom Identity Schemas it can help to keep track of changes. You can copy the Identity Schema directly from the Ory Network console or get it from the config file you pulled earlier.

For example:

//...
    # This is the default schema that's used for new identities
    "default_schema_id": "preset://email",
    # These are custom schemas that are available on your Ory Network project
    "schemas": [
      {
        "id": "7d1cf71e-57ae-40be-bddf-1f4c323e2349",
        "url": "https://storage.googleapis.com/bac-gcs-production/something.schema.json"
      },
    ],
//...

You can now save the default Identity Schema and custom Identity Schemas in git. When you make changes, convert the new Identity Schema to base64 and update it in the config file. You can only update existing identity schemas, to create a new one use the Ory Console. Use the following command to convert a file to base64 and copy it to the clipboard:

base64 < identity-schema.json | pbcopy

Now add the base64 encoded string to your configuration:

//...
    "schemas": [
      {
        "id": "7d1cf71e-57ae-40be-bddf-1f4c323e2349",
        "url": "base64://PASTE_BASE64_STRING_HERE"
      },
    ],
//...

When you update the configuration, Ory Network will automatically decode the base64 string and save the updated Identity Schema in the Ory Network backend.

Email Templates

You can also version and track email templates in the same way. One option is to create a folder in your repository for email templates and add the .html templates there. As with the other configurations you have to convert it into base64 and add it to the config file, whenever you make changes to the template.

Read the Custom email templates with Ory blog post to learn more about email template configuration via the Ory CLI.