Oracle by Example brandingUse Oracle Identity Cloud Service's Software Development Kit (SDK) for Authentication in .NET Web Applications

section 0Before You Begin

This 15 minutes tutorial shows you how to use Oracle Identity Cloud Service's Software Development Kit (SDK) for the ASP.NET framework to enable a sample web application to authenticate with Oracle Identity Cloud Service.

Series

This is a tutorial in the Use Oracle Identity Cloud Service's Software Development Kit (SDK) series. Read them in any order.

Background

Oracle Identity Cloud Service provides a Software Development Kit (SDK) that you can use to integrate .NET web applications with Oracle Identity Cloud Service.

The .NET SDK is available as a dynamic link library (dll) file, called IdcsClient.dll, and other complimentary dll files in IdcsClient/bin/Release/ folder, which must all be included in your .NET web application library.

To help you understand how to use the SDK, this tutorial uses a sample web application as a reference.

Important: The sample web application isn't meant to be published to production and isn't concerned about the language’s specific best practices, such as data handling, patterns, security, and so on. The sole purpose of the sample web application is to address the recommended approach to integrate Oracle Identity Cloud Service and a custom application using the SDK.

What Do You Need?

  • A basic knowledge of ASP.NET framework, ASP and C# programming languages to understand the code logic presented in this tutorial.
  • To install an ASP.NET Integrated Development Environment (IDE) for development, deployment, and testing purposes. This tutorial uses Microsoft Visual Studio 2017.
  • The SDK requires that .NET Framework 4.7.2 is installed in your IDE. DuringVisual Studio 2017 installation choose ASP.NET and web development workload, ASP.NET MVC 4, and at least .NET framework 4.7.2.
  • To download the NET sample web application zip file, and unzip it to the c:\temp folder of your desktop.
  • Access to an instance of Oracle Identity Cloud Service, and rights to download the SDK from the console and to add a confidential application.

section 1Download the SDK in the Sample Web Application

  1. Log in to Oracle Identity Cloud Service.
  2. In the Identity Cloud Service console, expand the Navigation Drawer Navigation Drawer, click Settings, and then click Downloads. The list of files to download appears.
  3. Click Download to download the Identity Cloud Service SDK for .NET SDK file, and save the zip file.
  4. Extract the contents of the SDK zip file into the sample web application package folder (c:\temp\NET\SampleApp\packages\). The source code structure of the sample web application must be similar to the one below.
    c:\temp\NET\
              SampleApp\
                   packages\
                        IdcsClient\bin\Release\
                                          IdcsClient.dll
                                          ...
                        FileInfo.json
                   SampleApp\
                   SampleApp.sln
    

section 2Register the Sample Web Application with Oracle Identity Cloud Service

The sample web application needs a Client ID and Secret to establish communication with Oracle Identity Cloud Service. You also need to configure API permissions that must be granted to the sample web application. This section explains how to register the sample web application with Oracle Identity Cloud Service.

  1. In the Identity Cloud Service console, expand the Navigation Drawer Navigation Drawer, click Applications.
  2. In the Applications page, click Add.
    Register application
    Description of this image
  3. In the Add Application chooser dialog, click Confidential Application.
  4. Populate the Details pane as follows, and then click Next.
    • Name: SDK Web Application
    • Description: SDK Web Application
  5. In the Client pane, select Configure this application as a client now, and then populate the fields of this pane, as follows:
    • Allowed Grant Types: Select Client Credentials and Authorization Code.
    • Allow non-HTTPS URLs: Select this check box. The sample application works in non-HTTPS mode.
    • Redirect URL: http://localhost:3001/Home/Callback
    • Post Logout Redirect URL: http://localhost:3001
  6. In the Client pane, scroll down, click the Add button below Grant the client access to Identity Cloud Service Admin APIs.
    Grant the client access to Identity Cloud Service Admin APIs
    Description of this image
  7. In the Add App Role dialog window, select Authenticator Client and Me in the list, and then click Add.
  8. Click Next in the Client pane and in the following panes until you reach the last pane. Then click Finish.
  9. In the Application Added dialog box, make a note of the Client ID and Client Secret values (because your web application needs these values to integrate with Oracle Identity Cloud Service), and then click Close.
    Client ID and Client Secret values
    Description of this image
  10. To activate the application, click Activate.
    Activate Application
    Description of this image
  11. In the Activate Application? dialog box, click Activate Application.

    The success message The SDK Web Application application has been activated. appears.

  12. In the Identity Cloud Service console, click the user name at the top-right of the screen, and click Sign Out.

section 3Update the Sample Web Application

In this section, you update the sample application code to make it use Oracle Identity Cloud Service's SDK for NET programming language.

  1. Populate the values of the Client ID , Client Secret , and Oracle Identity Cloud Service's base URL in the following format: https://<domain>
  2. Edit the c:\temp\NET\SampleApp\SampleApp\Models\ConnectionOptions.cs file, update the GetOptions() method with the following content, and then save the file.
      public Dictionary<string, string> GetOptions()
            {
                this.options = new System.Collections.Generic.Dictionary<String, String>
                {
                    { "ClientId", "" },
                    { "ClientSecret", "" },
                    { "BaseUrl", "" },
                    { "AudienceServiceUrl", "" },
                    { "TokenIssuer", "https://identity.oraclecloud.com/" },
                    { "scope", "urn:opc:idm:t.user.me openid" },
                    { "redirectURL", "http://localhost:3001/Home/Callback" },
                    { "logoutSufix", "/oauth2/v1/userlogout"},
                    { "LogLevel", "0" },
                    { "ConsoleLog", "True" }
                };
                return this.options;
            }

section 4Run the Sample Web Application

In this section of the tutorial, you prepare, run, and test the sample web application.

  1. Run the Visual Studio 2017 IDE. Click File, click Open, and then click Project/Solution.
    Visual Studio 2017 Open project.
    Description of this image
  2. Navigate to the c:\temp\NET\SampleApp folder, and open the SampleApp.sln file.
  3. In the right side of the Visual Studio 2017, in the Solution Explorer, right click the References folder, and click Manage NuGet Packages.
    Visual Studio 2017 Open project.
    Description of this image

    The NuGet:SampleApp tab opens.

    Note: If the Solution Explorer is not visible, click View, and then click Solution Explorer to open it.

  4. In NuGet:SampleApp tab, click Restore at the top right to restore the packages the sample application need, and then close the tab.
  5. Click Build, and then click Build Solution.

    The following message appear in the Output window: Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped.

  6. To run the application, press the CTRL + F5 keys.

    A new browser window automatically opens the http://localhost:3001 URL.

    Note: The sample application uses the port 3001 to run in the IIS express (the embedded server). Make sure you don't have any other service running in this port, otherwise, the server start fails.

  7. In the browser window that opened, click Log In.
  8. In the Login page, click the Oracle red icon.
    Sample application's login page.
    Description of this image
  9. In the Oracle Identity Cloud Service Sign In page, sign in using your Oracle Identity Cloud Service credentials.

    After you sign in to Oracle Identity Cloud Service successfully, the browser is redirected to the /Private/Home page. The name of the logged-in user appears at the top-right side of the page.

  10. In the left menu, click My Profile.
  11. Verify that information associated with your profile appears in the center of the page.
    Sample application's user info page.
    Description of this image
  12. Click Log Out on the upper-right corner. The sample application finalizes the user session and redirects the browser to Oracle Identity Cloud Service's logout URL.
  13. After Oracle Identity Cloud Service logs the user off, it redirects the user browser to the sample application index page. This behavior happens because the sample application adds two parameters post_logout_redirect_uri and id_token_hint to the Oracle Identity Cloud Service logout URL, as per below:

    /oauth2/v1/userlogout?post_logout_redirect_uri=http%3A//localhost%3A3001&id_token_hint=<ID_TOKEN>

    The post_logout_redirect_uri parameter value must match the Post Logout Redirect URL parameter value you set during Register the Sample Web Application with Oracle Identity Cloud Service


more informationWant to Learn More?