New in IdentityServer4: Resource-based Configuration

For RC4 we decided to re-design our configuration object model for resources (formerly known as scopes).

I know, I know – we are not supposed to make fundamental breaking changes once reaching the RC status – but hey – we kind of had our “DNX” moment, and realized that we either change this now – or never.

Why did we do that?
We spent the last couple of years explaining OpenID Connect and OAuth 2.0 based architectures to hundreds of students in training classes, attendees at conferences, fellow developers, and customers from all types of industries.

While most concepts are pretty clear and make total sense – scopes were the most confusing part for most people. The abstract nature of a scope as well as the fact that the term scope has a somewhat different meaning in OpenID Connect and OAuth 2.0, made this concept really hard to grasp.

Maybe it’s also partly our fault, that we stayed very close to the spec-speak with our object model and abstraction level, that we forced that concept onto every user of IdentityServer.

Long story short – every time I needed to explain scope, I said something like “A scope is a resource a client wants to access.”..and “there are two types of scopes: identity related and APIs…”.

This got us thinking if it would make more sense to introduce the notion of resources in IdentityServer, and get rid of scopes.

What did we do?
Before RC4 – our configuration object model had three main parts: users, client, and scopes (and there were two types of scopes – identity and resource – and some overlapping settings between them).

Starting with RC4 – the configuration model does not have scope anymore as a top-level concept, but rather identity resources and API resources.

terminology

We think this is a more natural way (and language) to model a typical token-based system.

From our new docs:

User
A user is a human that is using a registered client to access resources.

Client
A client is a piece of software that requests tokens from IdentityServer – either for authenticating a user (requesting an identity token)
or for accessing a resource (requesting an access token). A client must be first registered with IdentityServer before it can request tokens.

Resources
Resources are something you want to protect with IdentityServer – either identity data of your users (like user id, name, email..), or APIs.

Enough talk, show me the code!
Pre-RC4, you would have used a scope store to return a flat list of scopes. Now the new resource store deals with two different resource types: IdentityResource and ApiResource.

Let’s start with identity – standard scopes used to be defined like this:

public static IEnumerable<Scope> GetScopes()
{
    return new List<Scope>
    {
        StandardScopes.OpenId,
        StandardScopes.Profile
    };
}

..and now:

public static IEnumerable<IdentityResource> GetIdentityResources()
{
    return new List<IdentityResource>
    {
        new IdentityResources.OpenId(),
        new IdentityResources.Profile()
    };
}

Not very different. Now let’s define a custom identity resource with associated claims:

var customerProfile = new IdentityResource(
    name:        "profile.customer",
    displayName: "Customer profile",
    claimTypes:  new[] { "name""status""location" });

This is all that’s needed for 90% of all identity resources you will ever define. If you need to tweak details, you can set various properties on the IdentityResource class.

Let’s have a look at the API resources. You used to define a resource-scope like this:

public static IEnumerable<Scope> GetScopes()
{
    return new List<Scope>
    {
        new Scope
        {
            Name = "api1",
            DisplayName = "My API #1",
 
            Type = ScopeType.Resource
        }
    };
}

..and the new way:

public static IEnumerable<ApiResource> GetApis()
{
    return new[]
    {
        new ApiResource("api1""My API #1")
    };
}

Again – for the simple case there is not a huge difference. The ApiResource object model starts to become more powerful when you have advanced requirements like APIs with multiple scopes (and maybe different claims based on the scope) and support for introspection, e.g.:

public static IEnumerable<ApiResource> GetApis()
{
    return new[]
    {
        new ApiResource
        {
            Name = "calendar",
 
            // secret for introspection endpoint
            ApiSecrets =
            {
                new Secret("secret".Sha256())
            },
 
            // claims to include in access token
            UserClaims =
            {
                JwtClaimTypes.Name,
                JwtClaimTypes.Email
            },
 
            // API has multiple scopes
            Scopes =
            {
                new Scope
                {
                    Name = "calendar.read_only",
                    DisplayName = "Read only access to the calendar"
                },
                new Scope
                {
                    Name = "calendar.full_access",
                    DisplayName = "Full access to the calendar",
                    Emphasize = true,
 
                    // include additional claim for that scope
                    UserClaims =
                    {
                        "status"
                    }
                }
            }
        }
    };

IOW – We reversed the configuration approach, and you now model APIs (which might have scopes) – and not scopes (that happen to represent an API).

We like the new model much better as it reflects how you architect a token-based system much better. We hope you like it too – and sorry for moving the cheese ;)

As always – give us feedback on the issue tracker. RTM is very close.

Posted in .NET Security, ASP.NET, OAuth, Uncategorized, WebAPI | 15 Comments

New in IdentityServer4: Multiple allowed Grant Types

In OAuth 2 some grant type combinations are insecure, that’s why we decided for IdentityServer3 that we’ll be defensive and allow only a single grant type per client.

During the last two years of implementing OAuth 2, it turned out that certain combinations of grant types actually do make sense and we adjusted IdentityServer3 to accommodate a couple of those scenarios. But there were still some common cases that either required you to create multiple client configurations for the same logical client – or configuration became a bit messy.

We fixed that in IdentityServer4 – we now allow almost all combinations of grant types for a single client – including the standard ones and extension grants that you add yourself.

We still check that the combination you choose will not result in a security problem – so we haven’t compromised security. Just made the configuration more flexible and easier to use.

See all the details here.

Posted in ASP.NET, IdentityServer, OAuth, OpenID Connect, WebAPI | Leave a comment

IdentityServer4 RC2 released

Yesterday we pushed IdentityServer4 RC2 to nuget. There are no big new features this time, but a lot of cleaning up, bug fixing and adding more tests.

We might add one or two more bigger things before RTM – but mainly we are in stabilization-mode right now.

All the docs have been updated, and the release notes give you more details on the changes.

Please go ahead and try it out – and give us feedback on the issue tracker. The more, the better.

Posted in .NET Security, ASP.NET, IdentityModel, IdentityServer, OAuth, OpenID Connect, WebAPI | Leave a comment

IdentityModel v2 released

IdentityModel is our protocol client library for various OpenID Connect and OAuth 2 endpoints like discovery, userinfo, token, introspection and token revocation. In addition it has some general purpose helpers like generating random numbers, base64 URL encoding, time-constant string comparison and X509 store access.

V1 is a PCL – but V2 now targets netstandard 1.3 (and classic .NET 4.5). Since we have quite a big user base for V1, we didn’t want to break anyone doing that change. This is the reason why v1 and v2 now live in separate repos and can evolve independently if needed.

See the readme for examples what IdentityModel can do – and – as always give us feedback via the issue tracker.

Posted in .NET Security, IdentityModel, OAuth, OpenID Connect, WebAPI | Leave a comment

New in IdentityServer4: Resource Owner Password Validation

Not completely new, but re-designed.

In IdentityServer3, we used the user service for both interactive as well as non-interactive authentication. In IdentityServer4, the interactive authentication is done by the UI.

OAuth 2 resource owner password validation is disabled by default – but you can add support for it by implementing and registering the IResourceOwnerPasswordValidator interface.

This gives you more flexibility as in IdentityServer3 since you get access to the raw request and you have more control over the token response via the new GrantValidationResult.

Posted in ASP.NET, IdentityServer, OAuth, WebAPI | Leave a comment

New in IdentityServer4: Support for Extension Grants

Well – this is not completely new, but we redesigned it a bit.

Extension grants are used to add support for non-standard token issuance scenarios to the token endpoint, e.g. translating between token types, delegation, federation, custom input or output parameters.

One of the common questions we got was how to implement identity delegation – instead of repeating myself here – I wrote proper documentation on the topic, and how to use IdentityServer4 to implement it.

Get the details here.

Posted in ASP.NET, IdentityServer, OAuth, WebAPI | Leave a comment

New in IdentityServer4: Default Scopes

Another small thing people have been asking for.

The scope parameter is optional in OAuth 2 – but we made the decision that clients always have to explicitly ask for the scopes they want to access.

We relaxed this requirement a bit in IdentityServer4. At the token endpoint, scope is now optional (IOW for client credentials, resource owner and extension grants requests). If no scope is specified – the client will automatically get a token that contains all explicitly allowed scopes (that’s a per client setting).

This makes it easier, especially for server to server type communication to provision new APIs without having to change the token requests in the clients.

Endpoint documentation here – Client settings here.

 

Posted in .NET Security, ASP.NET, IdentityServer, OAuth, OpenID Connect, WebAPI | 1 Comment