OAuthOptions

View as Markdown

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

NameTypeRequiredDefaultDescription
AppIdstringNo"6400aa06db64de001a31c8a9"App UID from Developer Hub. The default is Contentstack's own app.
ClientIdstringNo"Ie0FEfTzlfAHL4xM"Client ID of the app. The default is Contentstack's own app.
RedirectUristringNo"http://localhost:8184"Absolute http or https URI the app redirects to.
ClientSecretstring?NonullClient secret. Empty selects the PKCE flow.
ResponseTypestringNo"code"OAuth response type. Only "code" passes validation.
Scopestring[]?NonullScopes to request, such as cm.stacks.management:read.
UsePkceboolRead-onlytruetrue 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 NameReturnsDescription
IsValidTrue when the settings pass validation.Checks the settings without throwing.
ValidateThis 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.

NameTypeDescription
errorMessage (required)out string?

Receives the first problem found, or null.

Default: Not applicable

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);
}