From 27eeafed996fef33380387d090629f0be7cb4a49 Mon Sep 17 00:00:00 2001 From: OpenIddict Bot <32257313+openiddict-bot@users.noreply.github.com> Date: Mon, 12 Feb 2018 00:01:56 +0000 Subject: [PATCH] Update the documentation pages --- features/application-permissions.html | 276 ++++++++++++++++++++++++++ features/index.html | 119 +++++++++++ features/toc.html | 119 +++++++++++ guide/migration.html | 81 +------- manifest.json | 58 +++++- toc.html | 3 + 6 files changed, 569 insertions(+), 87 deletions(-) create mode 100644 features/application-permissions.html create mode 100644 features/index.html create mode 100644 features/toc.html diff --git a/features/application-permissions.html b/features/application-permissions.html new file mode 100644 index 0000000..9de3b2b --- /dev/null +++ b/features/application-permissions.html @@ -0,0 +1,276 @@ + + + + + + + + Application permissions + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+
+
+ +
+ +
+
+
+
+
+
+
+

Application permissions

+ +

Starting with RC2, OpenIddict includes an optional feature codenamed "app permissions" that allows +controlling and limiting the OAuth2/OpenID Connect features a client application is able to use.

+

3 categories of permissions are currently supported:

+
    +
  • Endpoint permissions
    • +
  • Grant type/flow permissions
    • +
  • Scope permissions.
    • +
+

Configuring application permissions is recommended when dealing with +third-party clients, to ensure they can only use the features they need.

+
+

Endpoint permissions

+

Definition

+

Endpoint permissions limit the endpoints a client application can use.

+

If no endpoint permission is explicitly granted, the client application +is allowed to use all the endpoints enabled in Startup.ConfigureServices().

+
+

Supported permissions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EndpointConstant
Authorization endpointOpenIddictConstants.Permissions.Endpoints.Authorization
Introspection endpointOpenIddictConstants.Permissions.Endpoints.Introspection
Logout/end session endpointOpenIddictConstants.Permissions.Endpoints.Logout
Revocation endpointOpenIddictConstants.Permissions.Endpoints.Revocation
Token endpointOpenIddictConstants.Permissions.Endpoints.Token
+

Example

+

In the following example, the mvc application is allowed to use the authorization, logout and +token endpoints but will get an error when trying to send an introspection or revocation request:

+
if (await manager.FindByClientIdAsync("mvc") == null)
+{
+    await manager.CreateAsync(new OpenIddictApplicationDescriptor
+    {
+        ClientId = "mvc",
+        ClientSecret = "901564A5-E7FE-42CB-B10D-61EF6A8F3654",
+        DisplayName = "MVC client application",
+        PostLogoutRedirectUris = { new Uri("http://localhost:53507/signout-callback-oidc") },
+        RedirectUris = { new Uri("http://localhost:53507/signin-oidc") },
+        Permissions =
+        {
+            OpenIddictConstants.Permissions.Endpoints.Authorization,
+            OpenIddictConstants.Permissions.Endpoints.Logout,
+            OpenIddictConstants.Permissions.Endpoints.Token
+        }
+    });
+}
+

Grant type permissions

+

Definition

+

Grant type permissions limit the flows a client application is allowed to use.

+

If no grant type permission is explictly attached to an application, all the flows enabled in Startup.ConfigureServices() +can be freely used by the application (as long as the authorization or token endpoint permissions are granted).

+
+

Supported permissions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Grant typeConstant
Authorization code flowOpenIddictConstants.Permissions.GrantTypes.AuthorizationCode
Client credentials flowOpenIddictConstants.Permissions.GrantTypes.ClientCredentials
Implicit flowOpenIddictConstants.Permissions.GrantTypes.Implicit
Password flowOpenIddictConstants.Permissions.GrantTypes.Password
Refresh token flowOpenIddictConstants.Permissions.GrantTypes.RefreshToken
+

To add a custom flow permission, you can use the following pattern:

+
OpenIddictConstants.Permissions.Prefixes.GrantType + "custom_flow_name"
+

Example

+

In the following example, the postman application can only use the authorization code flow +while console is restricted to the password and refresh_token flows:

+
if (await manager.FindByClientIdAsync("postman") == null)
+{
+    await manager.CreateAsync(new OpenIddictApplicationDescriptor
+    {
+        ClientId = "postman",
+        DisplayName = "Postman",
+        RedirectUris = { new Uri("https://www.getpostman.com/oauth2/callback") },
+        Permissions =
+        {
+            OpenIddictConstants.Permissions.GrantTypes.AuthorizationCode
+        }
+    });
+}
+
+if (await manager.FindByClientIdAsync("console") == null)
+{
+    await manager.CreateAsync(new OpenIddictApplicationDescriptor
+    {
+        ClientId = "console",
+        DisplayName = "Console",
+        Permissions =
+        {
+            OpenIddictConstants.Permissions.GrantTypes.Password,
+            OpenIddictConstants.Permissions.GrantTypes.RefreshToken
+        }
+    });
+}
+

Scope permissions

+

Definition

+

Scope permissions limit the scopes (standard or custom) a client application is allowed to use.

+

Like the other permissions, scope permissions are optional: if no scope permission is explictly attached, +a client application is free to specify any scope in the authorization or token requests.

+

The openid and offline_access scopes are special-cased by OpenIddict and don't require explicit permissions.

+
+

Example

+

In the following sample, the angular client is allowed to request the address, +profile and custom scopes: any other scope will result in an error being returned.

+
if (await manager.FindByClientIdAsync("angular") == null)
+{
+    await manager.CreateAsync(new OpenIddictApplicationDescriptor
+    {
+        ClientId = "angular",
+        DisplayName = "Angular",
+        RedirectUris = { new Uri("https://localhost:34422/callback") },
+        Permissions =
+        {
+            OpenIddictConstants.Permissions.Prefixes.Scope +
+                OpenIdConnectConstants.Scopes.Address,
+
+            OpenIddictConstants.Permissions.Prefixes.Scope +
+                OpenIdConnectConstants.Scopes.Profile,
+
+            OpenIddictConstants.Permissions.Prefixes.Scope + "custom"
+        }
+    });
+}
+
+
+ + +
+
+ + +
+ + + + + + diff --git a/features/index.html b/features/index.html new file mode 100644 index 0000000..ff2dca9 --- /dev/null +++ b/features/index.html @@ -0,0 +1,119 @@ + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+
+
+ +
+ +
+
+
+
+
+
+
+ +
+
+
+
+

Application permissions

+

Learn how to leverage permissions to control the OIDC features a client is allowed to use.

+
+
+
+
+
+
+ + +
+
+ + +
+ + + + + + diff --git a/features/toc.html b/features/toc.html new file mode 100644 index 0000000..c1dd727 --- /dev/null +++ b/features/toc.html @@ -0,0 +1,119 @@ + + + + + + + + Table of Content + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+
+
+
+
+ +
+ + +
+
+ + +
+ + + + + + diff --git a/guide/migration.html b/guide/migration.html index 5f18667..0b1e0ff 100644 --- a/guide/migration.html +++ b/guide/migration.html @@ -141,28 +141,6 @@ application.RedirectUris = new JArray(addresses).ToString(Formatting.None); } - - // Grant the application all the permissions. Don't hesitate to update - // the list to only grant the permissions really needed by the application. - if (string.IsNullOrEmpty(application.Permissions)) - { - var permissions = new[] - { - OpenIddictConstants.Permissions.Endpoints.Authorization, - OpenIddictConstants.Permissions.Endpoints.Introspection, - OpenIddictConstants.Permissions.Endpoints.Logout, - OpenIddictConstants.Permissions.Endpoints.Revocation, - OpenIddictConstants.Permissions.Endpoints.Token, - - OpenIddictConstants.Permissions.GrantTypes.AuthorizationCode, - OpenIddictConstants.Permissions.GrantTypes.ClientCredentials, - OpenIddictConstants.Permissions.GrantTypes.Implicit, - OpenIddictConstants.Permissions.GrantTypes.Password, - OpenIddictConstants.Permissions.GrantTypes.RefreshToken - }; - - application.Permissions = new JArray(permissions).ToString(Formatting.None); - } } // If you use a different entity type or a custom key, @@ -199,60 +177,11 @@ UpdateOpenIddictTablesAsync(app.ApplicationServices).GetAwaiter().GetResult(); }

Run your application. Once it's correctly started, stop it and remove the migration script.

-

If necessary, update your code to grant applications the required permissions

-

If you have code that relies on OpenIddictApplicationManager.CreateAsync(OpenIddictApplicationDescriptor), -make sure that the appropriate set of permissions is granted.

-

For instance, to allow a client application to use the password and refresh token flows, you must grant the following permissions:

-
var descriptor = new OpenIddictApplicationDescriptor
-{
-    // ...
-    Permissions =
-    {
-        OpenIddictConstants.Permissions.Endpoints.Token,
-        OpenIddictConstants.Permissions.GrantTypes.Password,
-        OpenIddictConstants.Permissions.GrantTypes.RefreshToken
-    }
-};
-
-await manager.CreateAsync(descriptor);
-

For the authorization code flow, the following permissions are required:

-
var descriptor = new OpenIddictApplicationDescriptor
-{
-    // ...
-    Permissions =
-    {
-        OpenIddictConstants.Permissions.Endpoints.Authorization,
-        OpenIddictConstants.Permissions.Endpoints.Token,
-        OpenIddictConstants.Permissions.GrantTypes.AuthorizationCode
-    }
-};
-
-await manager.CreateAsync(descriptor);
-

For custom flows, use the OpenIddictConstants.Permissions.Prefixes.GrantType constant:

-
var descriptor = new OpenIddictApplicationDescriptor
-{
-    // ...
-    Permissions =
-    {
-        OpenIddictConstants.Permissions.Endpoints.Token,
-        OpenIddictConstants.Permissions.Prefixes.GrantType + "google_token_exchange"
-    }
-};
-
-await manager.CreateAsync(descriptor);
-

If your application uses introspection or revocation, these endpoints must also be enable. E.g:

-
var descriptor = new OpenIddictApplicationDescriptor
-{
-    // ...
-    Permissions =
-    {
-        OpenIddictConstants.Permissions.Endpoints.Introspection,
-        OpenIddictConstants.Permissions.Endpoints.Revocation
-    }
-};
-
-await manager.CreateAsync(descriptor);
-

List of changes (for applications using custom stores)

+

Optionally, update your code to grant applications the minimum required permissions

+

Starting with RC2, OpenIddict includes an optional feature codenamed "app permissions" that allows +controlling and limiting the OAuth2/OpenID Connect features a client application is able to use.

+

To learn more about this feature, read the Application permissions documentation.

+

List of changes (for applications using custom stores)

Renamed properties

diff --git a/manifest.json b/manifest.json index 953939e..c4689c7 100644 --- a/manifest.json +++ b/manifest.json @@ -74,6 +74,42 @@ "is_incremental": false, "version": "" }, + { + "type": "Conceptual", + "source_relative_path": "features/application-permissions.md", + "output": { + ".html": { + "relative_path": "features/application-permissions.html", + "hash": "Q9YeZDb5Xi2qYUPZCIV2Fg==" + } + }, + "is_incremental": false, + "version": "" + }, + { + "type": "Conceptual", + "source_relative_path": "features/index.md", + "output": { + ".html": { + "relative_path": "features/index.html", + "hash": "XqKWaZORYS552qmlWgIl8A==" + } + }, + "is_incremental": false, + "version": "" + }, + { + "type": "Toc", + "source_relative_path": "features/toc.yml", + "output": { + ".html": { + "relative_path": "features/toc.html", + "hash": "mh8ipy1SiRiL3xGmh8dI9w==" + } + }, + "is_incremental": false, + "version": "" + }, { "type": "Conceptual", "source_relative_path": "guide/getting-started.md", @@ -104,7 +140,7 @@ "output": { ".html": { "relative_path": "guide/migration.html", - "hash": "LslsCYsgYfBwjVuKYi3brg==" + "hash": "LpaDiniOjh3+v0brkllWeQ==" } }, "is_incremental": false, @@ -152,7 +188,7 @@ "output": { ".html": { "relative_path": "toc.html", - "hash": "DXK29jBdtRMjNtYqHIIxxg==" + "hash": "AIuWUZ3w7ANfT7rrvxU/jA==" } }, "is_incremental": false, @@ -167,15 +203,6 @@ "incrementalPhase": "build" }, "processors": { - "ResourceDocumentProcessor": { - "can_incremental": false, - "details": "Processor ResourceDocumentProcessor cannot suppport incremental build because the processor doesn't implement ISupportIncrementalDocumentProcessor interface.", - "incrementalPhase": "build" - }, - "ConceptualDocumentProcessor": { - "can_incremental": false, - "incrementalPhase": "build" - }, "RestApiDocumentProcessor": { "can_incremental": false, "details": "Processor RestApiDocumentProcessor cannot suppport incremental build because the processor doesn't implement ISupportIncrementalDocumentProcessor interface.", @@ -186,6 +213,15 @@ "details": "Processor TocDocumentProcessor cannot suppport incremental build because the processor doesn't implement ISupportIncrementalDocumentProcessor interface.", "incrementalPhase": "build" }, + "ConceptualDocumentProcessor": { + "can_incremental": false, + "incrementalPhase": "build" + }, + "ResourceDocumentProcessor": { + "can_incremental": false, + "details": "Processor ResourceDocumentProcessor cannot suppport incremental build because the processor doesn't implement ISupportIncrementalDocumentProcessor interface.", + "incrementalPhase": "build" + }, "ManagedReferenceDocumentProcessor": { "can_incremental": false, "incrementalPhase": "build" diff --git a/toc.html b/toc.html index 41f4dac..bf93405 100644 --- a/toc.html +++ b/toc.html @@ -78,6 +78,9 @@
  • Migration guide
    • +
  • + Features +