OAuthOptions
OAuthOptions
OAuthOptions holds the settings of one Open Authorization (OAuth) app, in the Contentstack.Management.Core.Models namespace.
When to Use This Class: Set its properties to the values of your app in Developer Hub, then pass it to the OAuth method of ContentstackClient.
Conceptual Role: Acts as the configuration object of an OAuthHandler. Leave ClientSecret empty for the Proof Key for Code Exchange (PKCE) flow, or set it for the client secret flow.
Returns: OAuthOptions. The settings of one OAuth app.
Class-Level Properties
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| AppId | string | No | "6400aa06db64de001a31c8a9" | App UID from Developer Hub. The default is Contentstack's own app. |
| ClientId | string | No | "Ie0FEfTzlfAHL4xM" | Client ID of the app. The default is Contentstack's own app. |
| RedirectUri | string | No | "http://localhost:8184" | Absolute http or https URI the app redirects to. |
| ClientSecret | string? | No | null | Client secret. Empty selects the PKCE flow. |
| ResponseType | string | No | "code" | OAuth response type. Only "code" passes validation. |
| Scope | string[]? | No | null | Scopes to request, such as cm.stacks.management:read. |
| UsePkce | bool | Read-only | true | true when ClientSecret is null or empty. |
Class-Level Notes
Pick the flow with the client secret.
- Without ClientSecret, the handler uses PKCE. It creates a code verifier in AuthorizeAsync and sends it with the token exchange, so a public app, such as a desktop tool, keeps no secret.
- With ClientSecret, the handler sends the secret with the token exchange and every refresh. Keep a client secret on a server only.
Defaults.
- The default AppId, ClientId, and RedirectUri identify Contentstack's own OAuth app, which client.OAuth() uses. Set all three for your own app.
- The SDK does not send Scope to the token endpoint. It adds the scopes to the authorization URL only.
Validation runs when you create the handler.
- Validate runs inside client.OAuth(options), so invalid settings throw OAuthConfigurationException there. Call IsValid to check settings without an exception.
Method Index
| Method Name | Returns | Description |
|---|---|---|
| IsValid | True when the settings pass validation. | Checks the settings without throwing. |
| Validate | This method returns nothing. | Checks the settings and throws on the first problem. |
Class-Level Snippet
This snippet configures an app for the PKCE flow with two scopes, checks the settings, and prints the authorization URL.
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
OAuthOptions options = new OAuthOptions()
{
AppId = "<APP_ID>",
ClientId = "<CLIENT_ID>",
RedirectUri = "<REDIRECT_URI>",
Scope = new string[] { "cm.stacks.management:read", "cm.entries.management:read" }
};
if (!options.IsValid(out string? problem))
{
Console.WriteLine(problem);
return;
}
ContentstackClient client = new ContentstackClient();
try
{
OAuthHandler oauth = client.OAuth(options);
Console.WriteLine(await oauth.AuthorizeAsync());
}
catch (OAuthException e)
{
Console.WriteLine($"OAuth failed: {e.Message}");
}Methods
Each method of the OAuthOptions class has its own section below, with its parameters, validation rules, behavior, and examples.
IsValid
IsValid checks the Open Authorization (OAuth) settings and reports whether they pass, without throwing.
| Name | Type | Description |
|---|---|---|
| errorMessage (required) | out string? | Receives the first problem found, or null. |
Returns: bool. True when the settings pass validation.
Overloads
- IsValid(): This overload takes no parameters.
- IsValid(out string? errorMessage)
Validation
- There is no client-side validation, and IsValid never throws. It returns false on the first rule that fails.
Behavior
- Client-side only. IsValid sends no request.
- Checks the rules below in order and stops at the first failure:
- AppId, ClientId, RedirectUri, and ResponseType are not empty or blank.
- RedirectUri is an absolute URI with the http or https scheme.
- ResponseType is "code".
- Does not check that the app, client ID, or redirect URI exist in Developer Hub. A wrong value fails at the token exchange.
- Validate runs the same rules and throws instead.
Example
Basic usage: report a settings problem
using System;
using Contentstack.Management.Core.Models;
OAuthOptions options = new OAuthOptions() { AppId = "<APP_ID>", ClientId = "<CLIENT_ID>", RedirectUri = "localhost:8184" };
if (!options.IsValid(out string? problem))
{
// Prints the first failed rule, here the missing http or https scheme
Console.WriteLine(problem);
}All parameters: the overload without a message
using System;
using Contentstack.Management.Core.Models;
OAuthOptions options = new OAuthOptions() { AppId = "<APP_ID>", ClientId = "<CLIENT_ID>", RedirectUri = "<REDIRECT_URI>" };
Console.WriteLine(options.IsValid());Validate
Validate checks the Open Authorization (OAuth) settings and throws on the first rule that fails.
This method takes no parameters.
Returns: void. This method returns nothing.
Validation
- Throws OAuthConfigurationException if a rule fails, with the problem in Message. The rules are the ones the IsValid method lists.
Behavior
- Client-side only. Validate sends no request.
- client.OAuth(options) and the OAuthHandler constructor call Validate, so you need to call it yourself only to check settings early, for example at startup.
Example
Basic usage: check settings at startup
using System;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
OAuthOptions options = new OAuthOptions() { AppId = "<APP_ID>", ClientId = "", RedirectUri = "<REDIRECT_URI>" };
try
{
options.Validate();
}
catch (OAuthConfigurationException e)
{
// Fires because ClientId is empty
Console.WriteLine(e.Message);
}