Admin SDK (deprecated)

Admin SDK has been deprecated as it is legacy code and no longer maintained. Please have a look at the new IDS DTO (U4.IdentityServices.DTO) package which contains the IDS Data Transfer Objects similar to the ones used here by the Admin SDK but without the repository factory classes and methods.

A client side .NET library for programmatically configuring IDS is now available. It can be downloaded as NuGet packages from https://packages.u4pp.com/nuget U4.IdentityServices.AdminSdk. This is useful for all services that need self-provisioning features to Identity Services. The library can be used from both .NET Full and .NET Core. The SDK will auto discover what version of the administration API is used by the targeted IDS so programmers can make solutions that are version independent. Unit4 Identity Services provides .NET Client SDK for programmatic management at client side. The client SDK communicates to Admin API to perform operations on client objects.

Choosing the appropriate factory

There are two available factories for creating repositories in the SDK. RepositoryFactory and StaticRepositoryFactory. Which one you should use depends on if your program is stateful or stateless. For a stateful application where you can keep an instance of the factory around you should use the StaticRepositoryFactory. Then all data from the configuration will be kept inside the factory and you can just use the generic Create method to create repositories when you need them. If your application is stateless you will have to use the RepositoryFactory. When its configured it will return the state as a SdkState dto and you will need to keep it in a cookie or something similar to keep it available for each repository Create.

Configure a stateful application

Before you can use the StaticRepositoryFactory you need to configure it. You have two options:

If you are using bearer authentication and the client credentials flow (Machine to machine) you can use the ConfigureClientCredentialsAsync flow. Then the SDK will get the access token for you and provide it in the call to the API. If you are using a user centric flow you will need to get the access token yourself and provide it in ConfigureBearerAsync.

No state is returned from the configuration so once configured you can use the StaticRepositoryFactory instance to create the repositories you need.

    // Provide client id and secret to connect using a client credentials client
    await _repositoryFactory.ConfigureClientCredentialsAsync("base_address_for_ids", clientId, clientSecret);

    var clientRepository = _repositoryFactory.Create<Client>();

Configure a stateless application

If you have an application where you recreate the components for each call (for example a .net mvc application) you either need to configure the StaticRepositoryFactory for each call or you could use the RepositoryFactory. The RepositoryFactory returns the state as a dto when it is configured. You can then save it in a cookie or similar, retrieve it and provide it when you create a repository. You can Configure the RepositoryFactory for usage with GetBearerConfigAsync("base_address_for_ids", "AccessToken");

The state dto returned from the configuration must be used to create a specific repository

    // Provide a token to use Bearer authentication
    var sdkState = await _repositoryFactory.GetBearerConfigAsync("base_address_for_ids", token);

    // The config needs to be the SdkState that you got from the GetConfig call.
    var tenantRepository = _repositoryFactory.Create<Tenant>(sdkState);

Note: We do not support basic authentication.

Error handling

When configuring the factory you will get an Unauthorized exception if the UserName or Password is wrong or if the bearer token is not valid. For all other errors you will get an IdsApiConfigException. Using the created repository you will get an Unauthorized exception for authorization errors and an IdsApiException for all other errors. The SDK have implemented retries for transient errors.

Operations supported by the admin SDK:

Operation Description
Get Lists all the items from the repository
Get(id) Returns specific item based the parameter supplied
Add Adds an item to the repository
Update Updates an item in respective item repository
PartialUpdate Updates only specified fields on an item (patch)
Delete Removes the item from respective item repository
CreateSecret Generates a secret for an item (client or scope)
DeleteSecret Deletes secret
GetHistory Returns auditing information

Examples

Admin SDK can connect with IDS using bearer authentication mode. Programmers can perform CRUD operations on Client, Tenants and Scopes.

Below example describes how to initialize SDK objects and perform operations using bearer authentication against IDS.

    RepositoryFactory _repositoryFactory = new RepositoryFactory();
    //connect to admin API using bearer authentication
    SdkState _config = _repositoryFactory.GetBearerConfigAsync("base_address_for_ids", token);  
    CurrentUser _testUser = new CurrentUser("TestApp"); // Either use ClaimsPricipal or specify yourself.

Create Client

    //initialize a client object
    var client = new Client()
        {
          ClientId = Guid.NewGuid().ToString("N"),
          ClientName = "Name of the client",
          Flow = OidcFlow.Hybrid,
          AccessTokenType = AccessTokenType.Jwt, 
          AllowedScopes = new List<string> { "openid" }
        };

    var repository = _repositoryFactory.Create<Client>(_config);

    //add the Client to repository
    var clientAdded = await repository.Add(client, _testUser);

Update Client

    var clientToUpdate = new Client()
        {
          ClientId = "Existing_Client_Id",
          ClientName = "Updated name of existing client"
        };

    var repository = _repositoryFactory.Create<Client>(_config);

    //update the Client in repository
    await _repository.Update(client, _testUser);

Delete Client

    var repository = _repositoryFactory.Create<Client>(_config);

    //delete the Client in repository
    await _repository.Delete("Existing_Client_Id");