Your B2B SaaS App Just Got Better

Within Auth0 by Okta, the Organizations feature allows business-to-business (B2B) software-as-a-service (SaaS) providers to manage their partners and customers and to customize the ways that end users access their applications.

Through a programmatic toolset of APIs and SDKs or directly on the Auth0 dashboard, B2B SaaS providers can use Organizations to:

• Represent their business customers and partners in Auth0 and manage their membership
• Configure branded, federated login flows for each business
• Build administration capabilities into their products, using Organizations APIs, so that those businesses can manage their own organizations

Until now, Organizations was limited to user-based authentication in browser-based flows — but with the General Availability (GA) of Machine-to-Machine Access for Organizations, B2B SaaS providers can now define the Organization(s) that a given app can access on its own behalf, via the Client Credentials Flow, for each API. This change allows B2B SaaS providers to open up their APIs, enabling machine-to-machine (M2M) use cases while allowing access to sensitive data and operations of each Organization to be restricted to authorized parties.

Leading Use Cases

Let’s start with a quick look at what’s going on behind the scenes when a customer wants to interact with a B2B SaaS API via Client Credentials Flow. As depicted in the figure below:

1. First, the customer application gets an access token; with Machine-to-Machine Access for Organizations, the token request communicates new context through the organization parameter, and the token itself includes the corresponding org_idand org_name
2. Next, the customer application calls your API
3. Your API server validates that the target Organization for the requests matches the org_id/name included in the access token

Straightforward and familiar, right?

Indeed, by design, these are exactly the claims used in existing user-based Organizations login flows, allowing B2B SaaS providers to implement the same authorization logic for their APIs across both user and machine-to-machine access.

Now, let’s look at the two primary use cases that this additional context enables, using our fictitious Travel0 company.

Open up APIs to third-party applications

Using Auth0 Organizations and the Management API, Travel0 offers a self-service portal where customers can create and manage their own organizations.

Travel0 wants to make it easy for customers to build bots to help end users find and purchase adventures. Accordingly, as part of this portal, Travel0 allows customers to register their applications (e.g., the bots) to consume the Travel0 API on their own behalf.

In this use case, cross-organization access must be correctly controlled so that applications belonging to a particular organization can only access that organization’s data.

Machine-to-machine access for Organizations allows Travel0’s self-service portal to configure Client Credentials access for customer applications by associating them with a specific organization for each API.

As a result, the applications of Travel0’s customer Org X can only access the Travel0 API within the scope of Org X.

To accommodate aggregators, Travel0 could also configure access from a single application to several organizations.

Isolation of organizations for internal applications

Travel0 also has internal processes and CLI tools that need to access the Travel0 API using the Client Credentials Flow. To apply a unified access control strategy on the API, Travel0 wants requests from its own applications to be scoped to a specific organization so that only the right data is accessed in each case.

Travel0’s services aren’t bound to an individual customer, and Machine-to-Machine Access for Organizations enables Travel0 to configure an application to access any organization for each API using the Client Credentials Flow.

How Does It Work?

Extending Client Grants

You may have noticed that the use cases outlined above rely on knowing which Organizations an application is authorized to access.

To support this, we’ve built on the existing concept of Client Grants, which represent the APIs an application is authorized to access via the Client Credentials Flow. You can now use the Client Grants (1) to specify whether an application can or cannot access an API in the context of an Organization and (2) to control which Organizations the Application can access, with two options:

1. Allow an application to access one (or several) specific organizations. This is especially relevant for the first use case.
2. Allow an application to access all organizations. This is especially relevant for the second use case.

Let’s take a look at the details!

Configuring Machine-to-Machine Access for Organizations

To get started, you'll need to create one or multiple APIs and Organizations. After that, the process consists of three steps for each Application:

1. Create an Application and enable it to use the Client Credentials flow. To learn more, read Create Applications and Update Grant Types.
2. Create and configure one or more Client Grants establishing the APIs that can be accessed by the Application.
3. Associate each Client Grant with one or more Organizations.

To create a Client Grant between the Application and an API, simply enable the toggle that can be found in the APIs tab under Application details:

The Client Grant will now have two extra properties:

• Organization Support: Configures whether the Client Credentials requests will deny, allow, or require the organization parameter. When configuring the Client Grant using Management API, this field will be called organization_usage.
• Allow Machine-to-Machine access to any organization: Configures whether the Client Credentials requests will allow any Organization within the tenant. By default, access will have to be granted organization by organization. When configuring the Client Grant using Management API, this field will be called allow_any_organization.

The Client Grant can also be created and configured for Organization support using Management API:

curl -X POST --location 'https://{auth0Domain}/api/v2/client-grants' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "client_id": "0aFYaz2svVw7a5wGuNvvmaiW0pa2Fpga",
    "audience": "https://example-api",
    "scope": ["create:posts", "read:posts", "update:posts", "delete:posts"],
    "organization_usage": "require",
    "allow_any_organization": false
}'

If allow_any_organization has been set to true, you’re all set — jump to Getting a machine-to-machine token in the context of an Organization to discover the next steps. On the other hand, if you only want to allow access to specific organizations, please continue reading.

Granting access to concrete Organizations

Once the Client Grant has been configured, it’s time to authorize it to access a specific Organization. To do so, navigate to the organization you would like to grant access to and go to the new Machine to Machine Access tab. Click on the Add Access button and follow the steps to select the application and the API to which your Organization will have access. This will create an Organization Client Grant, which enables this permission.

The Organization Client Grants can also be created using Management API. Three new scopes control the access to this new resource:

• create: organization_client_grants
• read: organization_client_grants
• delete: organization_client_grants

This is an example request that will grant access to the org_Kpu9Q89v57IaZJVK Organization for the Application and API defined in the cgr_kapBApAJV3jYdfQq Client Grant.

curl -X POST --location 'https://{auth0Domain}/api/v2/organizations/org_Kpu9Q89v57IaZJVK/client-grants' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "grant_id": "cgr_kapBApAJV3jYdfQq"
}'

Getting a machine-to-machine token in the context of an Organization

Now that everything has been configured, we’re all set to use the feature. Let’s make a Client Credentials request, passing an organization parameter:

curl --location 'https://{auth0Domain}/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=0aFYaz2svVw7a5wGuNvvmaiW0pa2Fpga' \
--data-urlencode 'client_secret=••••••' \
--data-urlencode 'audience=https://example-api' \
--data-urlencode 'organization=org_Kpu9Q89v57IaZJVK'

The response received from Auth0 is as follows:

{
  "access_token": "eyJhbGciOi...XptRHPuRkw",
  "scope": "create:posts read:posts update:posts delete:posts",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Let’s decode the access_token payload:

{
  "iss": "https://{auth0Domain}/",
  "sub": "0aFYaz2svVw7a5wGuNvvmaiW0pa2Fpga@clients",
  "aud": "https://example-api",
  "iat": 1730308095,
  "exp": 1730394495,
  "scope": "create:posts read:posts update:posts delete:posts",
  "org_id": "org_Kpu9Q89v57IaZJVK",
  "gty": "client-credentials",
  "azp": "0aFYaz2svVw7a5wGuNvvmaiW0pa2Fpga"
}

As you can see, the access_token now contains the Organization ID in the org_id claim.

Default Organization

If you have any restrictions preventing you or your customers from sending an organization parameter in the Client Credentials request or want to use a standard OAuth library that does not support Auth0 Organizations, you can set a Default Organization in the corresponding Auth0 Application, which will be used in all the subsequent Client Credentials requests:

curl --location --request PATCH 'https://{auth0Domain}/api/v2/clients/0aFYaz2svVw7a5wGuNvvmaiW0pa2Fpga \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "default_organization": {
    "organization_id": "org_Kpu9Q89v57IaZJVK",
    "flows": ["client_credentials"]
  }
}'

Additional Resources

Ready to use Machine-to-Machine Access for Organizations? Dive into our comprehensive documentation for details.

Need a quick refresher on Auth0 Organizations? Watch our demo video and browse the documentation.

Want a hands-on experience with essential Customer Identity functionalities in B2B SaaS apps? Check out our reference B2B SaaS app SaaStart.