Before 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.
- Use Oracle Identity Cloud Service's Software Development Kit (SDK) for Authentication in Java Web Applications
- Use Oracle Identity Cloud Service's Software Development Kit (SDK) for Authentication in Node.js Web Applications
- Use Oracle Identity Cloud Service's Software Development Kit (SDK) for Authentication in Python Web Applications
- Use Oracle Identity Cloud Service's Software Development Kit (SDK) for Authentication in .NET Web Applications
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.
Download the SDK in the Sample Web Application
- Log in to Oracle Identity Cloud Service.
- In the Identity Cloud Service console, expand the Navigation Drawer
, click Settings, and then click Downloads. The list of files to download appears.
- Click Download to download the Identity Cloud Service SDK for .NET SDK file, and save the zip file.
- 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
Register 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.
- In the Identity Cloud Service console, expand the Navigation Drawer
, click Applications.
- In the Applications page, click Add.
Description of this image - In the Add Application chooser dialog, click Confidential Application.
- Populate the Details pane as follows, and then click Next.
- Name:
SDK Web Application
- Description:
SDK Web Application
- Name:
- 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
- In the Client pane, scroll down, click the Add button below Grant the client access to Identity Cloud Service Admin APIs.
Description of this image - In the Add App Role dialog window, select Authenticator Client and Me in the list, and then click Add.
- Click Next in the Client pane and in the following panes until you reach the last pane. Then click Finish.
- 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.
Description of this image - To activate the application, click Activate.
Description of this image - In the Activate Application? dialog box, click Activate Application.
The success message The SDK Web Application application has been activated. appears.
- In the Identity Cloud Service console, click the user name at the top-right of the screen, and click Sign Out.
Update 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.
- Populate the values of the Client ID , Client Secret , and Oracle Identity Cloud Service's base URL in the following format: https://<domain>
- Edit the
c:\temp\NET\SampleApp\SampleApp\Models\ConnectionOptions.cs
file, update theGetOptions()
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; }
Run the Sample Web Application
In this section of the tutorial, you prepare, run, and test the sample web application.
- Run the Visual Studio 2017 IDE. Click File, click Open, and then click Project/Solution.
Description of this image - Navigate to the
c:\temp\NET\SampleApp
folder, and open theSampleApp.sln
file. - In the right side of the Visual Studio 2017, in the Solution Explorer, right click the References folder, and click Manage NuGet Packages.
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.
- In NuGet:SampleApp tab, click Restore at the top right to restore the packages the sample application need, and then close the tab.
- 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
. - 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. - In the browser window that opened, click Log In.
- In the Login page, click the Oracle red icon.
Description of this image - 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.
- In the left menu, click My Profile.
- Verify that information associated with your profile appears in the center of the page.
Description of this image - 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.
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