New message text here

While it's technically possible to use claims to store user permissions in a JWT token, it's generally not recommended in the Ory ecosystem for several reasons: 1. Claims are not designed for permissions: According to the [OAuth2 concepts documentation](https://www.ory.sh/docs/oauth2-oidc/overview/oauth2-concepts#oauth2-scopes-represent-user-consent), OAuth2 scopes represent user consent, not permissions. Claims are typically used for user information, not for storing complex permission structures. 2. Limited flexibility: As mentioned in the [Ory Keto introduction](https://www.ory.sh/docs/ecosystem/projects#ory-keto), permission systems often become more complex over time. Storing permissions in JWT claims would limit your ability to implement advanced access control scenarios that Ory Keto supports. 3. Security concerns: Storing detailed permissions in a JWT could potentially expose sensitive information about your system's structure if the token is intercepted. 4. Token size and performance: Including extensive permission data in JWT claims could lead to large tokens, increasing overhead in API requests. 5. Real-time updates: Permissions stored in JWT claims would be static until the token expires or is refreshed. This limits your ability to update permissions in real-time. 6. Separation of concerns: Ory's architecture is designed to separate authentication (handled by Ory Hydra or Ory Kratos) from authorization (handled by Ory Keto). This separation allows for more flexible and scalable systems. Instead of using claims for permissions, it's recommended to use Ory Keto for permission management. You can use JWTs for authentication and then use Ory Keto to check permissions based on the authenticated user's identity. If you need to include some user-specific information in the JWT, you can use custom claims. As shown in the [Custom consent UI and custom claims documentation](https://www.ory.sh/docs/oauth2-oidc/jwt-access-token#custom-consent-ui-and-custom-claims-for-jwt-access-token), you can add custom claims to access tokens. However, these should be used for user information, not for storing complex permission structures.

Based on the knowledge sources provided, it's not recommended to use the OAuth2 Client Credentials Flow for user authentication against your public API. Here's why: 1. Purpose of Client Credentials Flow: The Client Credentials Flow is designed for machine-to-machine authentication, not for end-user authentication. As stated in the [Ory documentation](https://www.ory.sh/docs/oauth2-oidc/client-credentials), "The Client Credentials flow is used when an application needs to access its own resources, rather than a user's resources." 2. No user context: The Client Credentials Flow does not involve a user context. According to the [Ory OAuth2 concepts documentation](https://www.ory.sh/docs/oauth2-oidc/overview/oauth2-concepts#getting-a-client-token), this flow is "designed for non-interactive applications, such as automated processes or microservices, where the client is authenticated using its client ID and client secret." 3. Security concerns: Using this flow for user authentication could lead to security vulnerabilities. The [Ory documentation on running an OAuth2 server](https://www.ory.sh/run-oauth2-server-open-source-api-security/#oauth2-client-credentials-grant--machine-to-machine) mentions that the Client Credentials grant is often used for machine-to-machine authentication, not for individual users. 4. Better alternatives: For user authentication against a public API, you should consider using other OAuth2 flows that are designed for user authentication, such as the Authorization Code Flow. The [Ory documentation on the Authorization Code Flow](https://www.ory.sh/docs/oauth2-oidc/authorization-code-flow#web-server-app-and-confidential-client) provides an example of how to implement this for web applications. Instead of using the Client Credentials Flow for user authentication, consider implementing one of these alternatives: 1. Authorization Code Flow: This is more suitable for user authentication in web applications. 2. OpenID Connect: This is an identity layer built on top of OAuth2, specifically designed for authentication. Remember, the choice of flow depends on your specific use case and security requirements. If you need more detailed guidance on which flow to use for your particular scenario, you may want to consult the Ory documentation further or reach out to Ory support for personalized advice.

Yes, you're correct. For API users, it would generally be better to use API Keys or Personal Access Tokens instead of the OAuth Client Credentials Flow. Let's explore why based on the information from our knowledge sources: 1. Purpose: API Keys and Personal Access Tokens are specifically designed for API access. As mentioned in the [Ory Network API Keys documentation](https://www.ory.sh/docs/concepts/personal-access-token), "API Keys are used to authorize privileged operations to Ory Network Project Admin APIs." 2. Simplicity: API Keys are simpler to implement and use compared to the OAuth Client Credentials Flow. They don't require the complex OAuth2 dance and can be easily included in API requests. 3. User-specific: Personal Access Tokens are typically associated with a specific user or service account, making them more appropriate for individual API users than the Client Credentials Flow, which is more suited for machine-to-machine communication. 4. Security: Ory API Keys have a built-in security feature. As stated in the documentation, "Ory API Keys have a

ory_apikey_

or

ory_pat_

prefix, which makes it easy to identify them when analyzing code." 5. Flexibility: API Keys can be easily created, rotated, and revoked through the Ory Console, providing better control over access management. 6. Scoping: While not explicitly mentioned in the provided sources, API Keys and Personal Access Tokens can often be scoped to specific permissions or resources, allowing for fine-grained access control. Here's an example of how to use an API Key with Ory, as shown in the documentation:

GET /admin/identities HTTP/1.1 Host: $<http://PROJECT_SLUG.projects.oryapis.com|PROJECT_SLUG.projects.oryapis.com> Accept: application/json Authorization: Bearer $API_KEY

This approach is more straightforward and appropriate for most API access scenarios compared to implementing the OAuth Client Credentials Flow. Remember, the choice between API Keys, Personal Access Tokens, and OAuth flows depends on your specific use case and security requirements. For most API users, especially when dealing with Ory's Admin APIs, API Keys or Personal Access Tokens would be the recommended approach.

I apologize, but I need to correct a misunderstanding in your statement. Ory does provide API keys that can be used within your system. Let me clarify this based on the information from our knowledge sources: 1. Project API Keys: Ory Network provides API keys for project-level operations. As stated in the [Ory Network API Keys documentation](https://www.ory.sh/docs/concepts/personal-access-token), "API Keys are used to authorize privileged operations to Ory Network Project Admin APIs." These keys can be created and managed through the Ory Console. 2. Workspace API Keys: For managing multiple projects or for B2B scenarios, Ory offers Workspace API keys. According to the [Manage Ory Network projects through the API guide](https://www.ory.sh/docs/guides/manage-project-via-api), "Workspace API keys are used to authorize privileged operations to Ory Network Workspace admin APIs as well as the project admin APIs of all projects that belong to this workspace." 3. Creation Process: You can create these API keys easily. For Project API keys, go to "Project settings → API Keys" in the Ory Console. For Workspace API keys, go to "Workspace settings → API keys" in the Ory Console. 4. Usage: These API keys can be used in your system to interact with Ory's APIs. Here's an example of how to use an API key:

GET /admin/identities HTTP/1.1    Host: $<http://PROJECT_SLUG.projects.oryapis.com|PROJECT_SLUG.projects.oryapis.com>    Accept: application/json    Authorization: Bearer $API_KEY

5. Identification: Ory API Keys have specific prefixes for easy identification. As mentioned in the documentation, "Ory API Keys have a

ory_apikey_

or

ory_pat_

prefix, which makes it easy to identify them when analyzing code." If you're having trouble creating or using API keys within your Ory project, I recommend checking the [Ory Console](https://console.ory.sh/) or reaching out to Ory support for assistance. They should be able to help you set up and use API keys within your system.

New message text here

Including roles as claims within a JWT is technically possible with Ory, but there are important considerations to make before implementing this approach. ### Adding Custom Claims to JWTs Ory does allow you to add custom claims to JWT tokens. As shown in the [Custom consent UI and custom claims documentation](https://www.ory.sh/docs/oauth2-oidc/jwt-access-token#custom-consent-ui-and-custom-claims-for-jwt-access-token), you can add custom claims during the consent acceptance process:

javascript await ory.acceptOAuth2ConsentRequest({   consentChallenge: consentChallenge,   acceptOAuth2ConsentRequest: {     session: {       access_token: {         user_roles: ["admin", "editor"],  // Example of adding roles       },     },   }, })

### Considerations for Including Roles in JWTs 1. Token Size: Including roles in JWTs increases token size, which means more data transmitted with every API request. 2. Immutability: As mentioned in the [JWT access tokens documentation](https://www.ory.sh/docs/oauth2-oidc/jwt-access-token#limitations), "Access Tokens as JSON Web Tokens can't be revoked: You can revoke a JWT token, but the token is still considered valid until the token's expiry time is reached." This means if a user's role changes, they'll still have access with their old role until their token expires. 3. Security Exposure: The [JWT access tokens documentation](https://www.ory.sh/docs/oauth2-oidc/jwt-access-token#limitations) also notes that "OAuth 2.0 Access Tokens represent internal state but are public knowledge: An Access Token often contains internal data (such as session data) or other sensitive data (such as user roles and permissions)." This means sensitive role information could potentially be exposed. 4. Complexity vs. Simplicity: For simple role-based access control, including roles in JWTs might be sufficient. However, for more complex permission scenarios, Ory Keto would be more appropriate as mentioned in the [Ory Keto documentation](https://www.ory.sh/docs/ecosystem/projects#ory-keto). ### Best Practices If you decide to include roles in JWTs: 1. Keep tokens short-lived to minimize the window of outdated role information. 2. Consider using the token introspection endpoint to validate tokens, which allows you to check if a token has been revoked. 3. For top-level claims, you'll need to modify the configuration as shown in the documentation:

ory patch oauth2-config --project <project-id> --workspace <workspace-id> \   --replace "/oauth2/allowed_top_level_claims=[\"user_roles\"]"

### Conclusion Including roles as claims in JWTs can be appropriate for simpler systems with relatively static role assignments. However, as your permission requirements grow more complex, you might want to consider using Ory Keto for more sophisticated access control, as it's specifically designed for handling complex permission scenarios. The best approach depends on your specific use case, the complexity of your permission model, and how frequently roles change in your system.

I'll help you understand how to handle subscription downgrades that affect OAuth Client Credentials flow scopes in Ory. This is a common challenge when managing OAuth clients with changing access levels. Based on the knowledge sources, there are a few approaches you could take: ### 1. Use Scope Strategy Configuration Ory allows you to configure how scopes are handled when requested scopes don't match allowed scopes. You could use the

default_grant_allowed_scope

setting:

ory patch oauth2-config "{your-project-id}" \   --replace '/oauth2/client_credentials/default_grant_allowed_scope=true'

As mentioned in the [Migrating from MITREid documentation](https://www.ory.sh/docs/hydra/self-hosted/migrating-from-mitreid), this setting makes Ory grant the OAuth2 Client's allowed scopes when a client requests scopes that are no longer permitted. ### 2. Token Introspection for Validation Instead of breaking the token issuance, you could still issue tokens but use token introspection to validate what the token can actually do: 1. Allow the client to get a token with the requested scopes 2. Use the [token introspection endpoint](https://www.ory.sh/docs/oathkeeper/pipeline/authn#oauth2_introspection) to validate what the token is actually allowed to do 3. Your API can then enforce the actual allowed scopes based on the current subscription level This approach is documented in the Oathkeeper pipeline authenticators section. ### 3. Scope Strategies for Graceful Degradation Ory supports different [scope strategies](https://www.ory.sh/docs/oathkeeper/api-access-rules#scoped-credentials) that could help with graceful degradation: - `hierarchic`: Scope

foo

matches

foo

,

foo.bar

,

foo.baz

but not

bar

- `wildcard`: Scope

foo.*

matches

foo

,

foo.bar

,

foo.baz

but not

bar

- `exact`: Scope

foo

matches

foo

but not

bar

nor

foo.bar

You could structure your scopes hierarchically based on subscription levels, allowing for graceful degradation. ### 4. Client Modification with Notification If you need to modify the client's allowed scopes, you could: 1. Use the [patchOAuth2Client API](https://www.ory.sh/docs/reference/api) to update the client's allowed scopes 2. Implement a notification system to inform your customers about the change 3. Provide a grace period where both old and new scopes work ### Best Practice Recommendation The most robust approach would be a combination of: 1. Structure your scopes hierarchically based on subscription tiers 2. When a downgrade occurs, update the client's allowed scopes but maintain backward compatibility through scope strategy configuration 3. Use token introspection to enforce the current subscription limitations 4. Notify customers about the change and provide documentation on how to update their integration This approach ensures that existing integrations don't break immediately while still enforcing the subscription limitations appropriately. Would you like more specific details on implementing any of these approaches?

Based on the knowledge sources provided, adding a service role to an application within the OAuth Client Credentials flow could make sense in certain scenarios, but it's important to understand the purpose and limitations of this approach. The OAuth Client Credentials flow is specifically designed for machine-to-machine authentication, not for end-user authentication. As stated in the [OAuth2 client credentials flow documentation](https://www.ory.sh/docs/oauth2-oidc/client-credentials), "The Client Credentials flow is used when an application needs to access its own resources, rather than a user's resources." If you're considering adding a service role to define what your application can access, there are a few approaches you could take: 1. Using scopes: When creating an OAuth2 client for the Client Credentials flow, you can define specific scopes that represent the service role's permissions:

ory create oauth2-client \   --grant-type client_credentials \   --scope my-scope \   --token-endpoint-auth-method client_secret_basic

2. Custom claims in tokens: As we discussed previously, you could include role information as custom claims in the JWT access token. This would allow your services to understand what role the client application has. 3. Client-specific permissions: You could create different OAuth2 clients with different scopes for different service roles, effectively using the client ID itself to represent a specific service role. Remember that in the Client Credentials flow, there is no user context - the client itself is being authenticated. As mentioned in the [OAuth2 concepts documentation](https://www.ory.sh/docs/oauth2-oidc/overview/oauth2-concepts#getting-a-client-token), this flow is "designed for non-interactive applications, such as automated processes or microservices, where the client is authenticated using its client ID and client secret." For more complex authorization scenarios, you might want to consider using Ory Keto alongside the OAuth Client Credentials flow, where the client gets authenticated via OAuth2, but the actual permission checks are handled by Keto. Would you like more specific information about implementing any of these approaches for your service roles?

Yes, the OAuth Client Credentials flow can be used as a replacement for API keys in many scenarios, particularly for machine-to-machine communication. Let me explain the advantages and considerations based on the Ory documentation. ### OAuth Client Credentials as API Key Alternative The Client Credentials flow is specifically designed for machine-to-machine authentication where a client application needs to access resources without a user context. As stated in the [OAuth2 client credentials documentation](https://www.ory.sh/docs/oauth2-oidc/client-credentials): > The Client Credentials flow is used when an application needs to access its own resources, rather than a user's resources. This makes it well-suited for API access scenarios where traditional API keys might be used. ### Advantages Over Simple API Keys 1. Token Expiration: Unlike static API keys, OAuth tokens expire, providing better security through time-limited access. 2. Scope Limitation: You can limit what the client can access using scopes, as shown in this example from the [Ory documentation](https://www.ory.sh/docs/hydra/guides/oauth2-clients#example-oauth2-clients):

ory create oauth2-client \      --grant-type client_credentials \      --scope my-scope \      --token-endpoint-auth-method client_secret_basic

3. Standardized Protocol: OAuth2 is a widely adopted standard with robust security practices. 4. Flexible Authentication Methods: Ory supports multiple authentication methods for clients, including: - Basic Authentication (client ID and secret in Authorization header) - Body Authentication (client ID and secret in request body) - JWT Bearer profile (using signed JWTs) as described in the [JWT Bearer documentation](https://www.ory.sh/docs/oauth2-oidc/client-credentials#jwt-bearer-profile-for-oauth2-client-authentication) ### Implementation Example Here's a basic example of how to implement this flow from the [Ory documentation](https://www.ory.sh/blog/run-oauth2-server-open-source-api-security): 1. Create an OAuth2 client:

ory create oauth2-client --project $project_id \        --name "Client Credentials Demo" \        --grant-type client_credentials

2. Exchange credentials for a token:

ory perform client-credentials --project $project_id \      --client-id=$client_id \      --client-secret=$client_secret

3. Use the token to access your API resources. ### Considerations 1. Complexity: OAuth2 is more complex to implement than simple API keys. 2. Token Validation: Your API will need to validate tokens, which can be done through token introspection as shown in the [Oathkeeper documentation](https://www.ory.sh/docs/oathkeeper/pipeline/authn#oauth2_introspection). 3. Use Case Appropriateness: As mentioned in the [Hydra concepts documentation](https://www.ory.sh/docs/hydra/concepts/before-oauth2), OAuth2 is not always necessary for every use case. For your specific scenario of replacing API keys for your customers to access your API, the Client Credentials flow would be an appropriate and more secure alternative to static API keys, especially if you need fine-grained access control through scopes.

I'll explain how to control client permissions in an OAuth Client Credentials flow scenario with Ory. When using the OAuth Client Credentials flow as an API key replacement, you have several options to control the permissions of the client: ### 1. Using OAuth2 Scopes The primary mechanism for controlling permissions is through OAuth2 scopes. When creating an OAuth2 client, you can define which scopes it's allowed to request:

ory create oauth2-client \   --grant-type client_credentials \   --scope photos.read --scope users.write --scope analytics.view \   --token-endpoint-auth-method client_secret_post

As shown in the [Hydra guides documentation](https://www.ory.sh/docs/hydra/guides/oauth2-clients), you can specify multiple scopes that define what the client is allowed to access. ### 2. Audience Restriction You can further restrict which resources (APIs) the client can access by defining audiences:

ory create oauth2-client \   --grant-type client_credentials \   --audience "<https://api.my-cloud.com/user>" \   --audience "<https://some-tenant.my-cloud.com/>" \   --token-endpoint-auth-method client_secret_post

As explained in the [OAuth2 token audience documentation](https://www.ory.sh/docs/hydra/guides/audiences), the audience claim in the token defines at which endpoints the token can be used. ### 3. Token Introspection for Validation Your API services should validate tokens using introspection to check if the token is valid and has the required scopes:

ory introspect token --project $project_id $access_token

The introspection response will include the scopes and audiences associated with the token, allowing your API to make authorization decisions. ### 4. Combining with Ory Keto for Advanced Permissions For more complex permission scenarios, you can combine the Client Credentials flow with Ory Keto: 1. Authenticate the client using OAuth2 Client Credentials 2. Use the client identifier from the token to check permissions in Keto 3. Make authorization decisions based on Keto's response As mentioned in the [Ory Keto documentation](https://www.ory.sh/docs/ecosystem/projects#ory-keto), Keto is designed for complex permission scenarios and can "authenticate different types of credentials (for example OAuth 2.0 Access Tokens, SAML Assertions, JSON Web Tokens, ...)" and allows you to "define advanced permission rules." ### 5. Subscription-Based Permission Management For handling subscription-based permissions as you mentioned earlier, you could: 1. Structure your scopes hierarchically based on subscription tiers 2. Update client permissions when subscriptions change 3. Use token introspection to enforce current subscription limitations This approach allows you to manage permissions dynamically based on business rules while maintaining a clean technical implementation. By combining these approaches, you can create a robust permission system for your API clients that balances security, flexibility, and ease of use. Would you like more specific details on implementing any of these approaches?

I can help you update the OAuth2 scope strategy from

wildcard

to

hierarchic

using the Ory CLI. This is a straightforward configuration change that can be done with the

patch

command. Here's how to update the OAuth2 scope strategy:

ory patch oauth2-config --project <project-id> --workspace <workspace-id> \   --replace '/oauth2/scope_strategy="hierarchic"'

This command uses the

ory patch

functionality to update a specific configuration value in your OAuth2 settings, as shown in the [Ory CLI OAuth2 configuration guide](https://www.ory.sh/docs/guides/cli/oauth2-cli). The scope strategy determines how scopes are matched and validated. When you change from

wildcard

to `hierarchic`: - In

wildcard

mode: Scope

foo.*

matches

foo

,

foo.bar

,

foo.baz

but not

bar

. Scope

foo

matches

foo

but not

foo.bar

. - In

hierarchic

mode: Scope

foo

matches

foo

,

foo.bar

,

foo.baz

but not

bar

. This change affects how Ory validates scopes in various contexts, including token validation and permission checks, as described in the [Oathkeeper API access rules documentation](https://www.ory.sh/docs/oathkeeper/api-access-rules#scoped-credentials). If you're using Ory Oathkeeper with Ory Hydra, remember that you should keep the scope strategy in sync between both services as mentioned in the [Oathkeeper OAuth2 token introspection documentation](https://www.ory.sh/docs/oathkeeper/oauth2-token-introspection-hydra). Would you like me to explain more about how the hierarchic scope strategy works or how it might affect your existing OAuth2 clients? kapa.ai: I've answered your question about updating the OAuth2 scope strategy from wildcard to hierarchic using the Ory CLI. I've provided the exact command you need, explained the difference between these strategies, and mentioned important considerations about keeping scope strategies in sync across Ory services. Let me know if you need any clarification or have follow-up questions!

I apologize for the confusion. You're right that there might be a discrepancy between the CLI command parameter and what's shown in the Ory OAuth UI. Based on the knowledge sources provided, the correct way to update the OAuth2 scope strategy using the CLI is:

ory patch oauth2-config --project <project-id> \   --replace '/strategies/scope="hierarchic"'

This is shown in the [Ory patch oauth2-config documentation](https://www.ory.sh/docs/cli/ory-patch-oauth2-config#ory-patch-oauth2-config), where the path structure follows the format

/strategies/scope

. The variable name

hydra_strategies_scope

that you're seeing in the Ory OAuth UI likely refers to the same configuration setting, but with a different naming convention used in the UI compared to the CLI command. When using the patch command, you need to follow the JSON path structure of the configuration. In this case, the scope strategy is located under the

strategies

object with the key

scope

. If you're still encountering issues with the command, you might want to first check your current configuration with:

ory get oauth2-config --project <project-id> --format json-pretty

This will show you the exact structure of your configuration and help confirm the correct path to use in your patch command.

I see the issue with your command. Based on the error message, it appears that the allowed values for the scope strategy in Ory are limited to "exact" and "wildcard", and "hierarchic" is not a valid option despite being mentioned in some documentation. According to the [Ory Oathkeeper API access rules documentation](https://www.ory.sh/docs/oathkeeper/api-access-rules#scoped-credentials), there are several scope strategies including "hierarchic", "exact", "wildcard", and "none". However, it seems that the OAuth2 configuration in Ory Network might have a more limited set of options. To fix this issue, you should use one of the allowed values:

ory patch oauth2-config --project <project-id> --replace '/strategies/scope="exact"'

or

ory patch oauth2-config --project <project-id> --replace '/strategies/scope="wildcard"'

This discrepancy might be due to differences between Ory Oathkeeper's scope strategies and Ory Hydra's scope strategies, or it could be that the documentation is referring to a feature that's available in self-hosted versions but not in Ory Network. If you specifically need the hierarchical scope strategy functionality, you might want to: 1. Check if there's a newer version of the Ory CLI that supports this option 2. Contact Ory support to confirm if this feature is available in your subscription tier 3. Consider using the "exact" strategy and structuring your permissions differently to achieve similar results Would you like me to explain how you might adapt your permission structure to work with the available scope strategies? kapa.ai: I've explained why you're getting an error when trying to set the scope strategy to "hierarchic" and provided alternative commands using the allowed values. I've also suggested some next steps if you specifically need hierarchical scope functionality.