From 222a8c16944207c6620c82033f28028d14811bd2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Chalet?= Date: Wed, 4 Jul 2018 13:12:29 +0200 Subject: [PATCH] Update the application permissions documentation --- features/application-permissions.md | 78 +++++++++++++++++++++-------- 1 file changed, 58 insertions(+), 20 deletions(-) diff --git a/features/application-permissions.md b/features/application-permissions.md index 6949df5..f8d2431 100644 --- a/features/application-permissions.md +++ b/features/application-permissions.md @@ -1,15 +1,22 @@ # 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. +Starting with RC2, OpenIddict includes a built-in feature codenamed "application 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. +> [!WARNING] +> Note: **prior to OpenIddict RC3, application permissions were mostly optional** and OpenIddict had a fallback mechanism +> called "implicit permissions" it used to determine whether an application could perform the requested action. +> +> If no permission was explicitly attached to the application, it was considered fully trusted and was granted all the permissions. +> Similarly, if you granted the "token endpoint" permission to an application but NO "grant type" permission, +> it was assumed the client application was allowed to use the password or client credentials grants. +> +> Retrospectively, this logic was too complex and it removed in RC3 and **application permissions MUST now be explicitly granted**. ## Endpoint permissions @@ -17,9 +24,6 @@ third-party clients, to ensure they can only use the features they need. 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 | Endpoint | Constant | @@ -55,15 +59,24 @@ if (await manager.FindByClientIdAsync("mvc") == null) } ``` +### Disabling endpoint permissions + +If you don't want to use endpoint permissions, call `options.IgnoreEndpointPermissions()` to ignore them: + +```csharp +services.AddOpenIddict() + .AddServer(options => + { + options.IgnoreEndpointPermissions(); + }); +``` + ## 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 type | Constant | @@ -94,6 +107,9 @@ if (await manager.FindByClientIdAsync("postman") == null) RedirectUris = { new Uri("https://www.getpostman.com/oauth2/callback") }, Permissions = { + OpenIddictConstants.Permissions.Endpoints.Authorization, + OpenIddictConstants.Permissions.Endpoints.Token, + OpenIddictConstants.Permissions.GrantTypes.AuthorizationCode } }); @@ -107,6 +123,8 @@ if (await manager.FindByClientIdAsync("console") == null) DisplayName = "Console", Permissions = { + OpenIddictConstants.Permissions.Endpoints.Token, + OpenIddictConstants.Permissions.GrantTypes.Password, OpenIddictConstants.Permissions.GrantTypes.RefreshToken } @@ -114,21 +132,30 @@ if (await manager.FindByClientIdAsync("console") == null) } ``` +### Disabling grant type permissions + +If you don't want to use grant type permissions, call `options.IgnoreGrantTypePermissions()` to ignore them: + +```csharp +services.AddOpenIddict() + .AddServer(options => + { + options.IgnoreGrantTypePermissions(); + }); +``` + ## 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. +`profile` and `marketing_api` scopes: any other scope will result in an error being returned. ```csharp if (await manager.FindByClientIdAsync("angular") == null) @@ -140,14 +167,25 @@ if (await manager.FindByClientIdAsync("angular") == null) RedirectUris = { new Uri("https://localhost:34422/callback") }, Permissions = { - OpenIddictConstants.Permissions.Prefixes.Scope + - OpenIdConnectConstants.Scopes.Address, + OpenIddictConstants.Permissions.Endpoints.Authorization, + OpenIddictConstants.Permissions.GrantTypes.Implicit, - OpenIddictConstants.Permissions.Prefixes.Scope + - OpenIdConnectConstants.Scopes.Profile, - - OpenIddictConstants.Permissions.Prefixes.Scope + "custom" + OpenIddictConstants.Permissions.Scopes.Address, + OpenIddictConstants.Permissions.Scopes.Profile, + OpenIddictConstants.Permissions.Prefixes.Scope + "marketing_api" } }); } +``` + +### Disabling scope permissions + +If you don't want to use scope permissions, call `options.IgnoreScopePermissions()` to ignore them: + +```csharp +services.AddOpenIddict() + .AddServer(options => + { + options.IgnoreScopePermissions(); + }); ``` \ No newline at end of file