Home / powershell base64 encode file / apimgmtstuedabtrty2yy58h.blob.core.

apimgmtstuedabtrty2yy58h.blob.core. - powershell base64 encode file



-914400-81026000API Gateway – Authentication and Authorisation Overview-12708508365employment.gov.au400000employment.gov.auFor external developersApr 2021Contents TOC \o "1-3" \h \z \u Document History PAGEREF _Toc71814063 \h 41. Introduction PAGEREF _Toc71814064 \h 51.1 General PAGEREF _Toc71814065 \h 51.2 Scenario decision tree PAGEREF _Toc71814066 \h 51.3 Document Conventions PAGEREF _Toc71814067 \h 51.4 Intended Audience PAGEREF _Toc71814068 \h 61.5 References PAGEREF _Toc71814069 \h 6Official Standard PAGEREF _Toc71814070 \h 6A Guide to OAuth 2.0 Grants PAGEREF _Toc71814071 \h 61.6 Contact Details PAGEREF _Toc71814072 \h 6API Product Manager PAGEREF _Toc71814073 \h 61.7 Prerequisites for all scenarios PAGEREF _Toc71814074 \h 72. Scenario 1 – Third Party Client Application PAGEREF _Toc71814075 \h 82.1 Brief Description PAGEREF _Toc71814076 \h 82.2 Scenario Characteristics PAGEREF _Toc71814077 \h 82.3 Scenario Synopsis PAGEREF _Toc71814078 \h 83. Scenario 2 – Web Application PAGEREF _Toc71814079 \h 123.1 Brief Description PAGEREF _Toc71814080 \h 123.2 Scenario Characteristics PAGEREF _Toc71814081 \h 123.3 Scenario Synopsis PAGEREF _Toc71814082 \h 124. Scenario 3 – Service-to-service PAGEREF _Toc71814083 \h 174.1 Brief Description PAGEREF _Toc71814084 \h 174.2 Scenario Characteristics PAGEREF _Toc71814085 \h 174.3 Scenario Synopsis PAGEREF _Toc71814086 \h 184.4 Scenario Variation for 3rd Party IT Houses PAGEREF _Toc71814087 \h 206. Glossary PAGEREF _Toc71814088 \h 21Appendix A – Certificate and encoding specification PAGEREF _Toc71814089 \h 23A.1 - Certificate specification PAGEREF _Toc71814090 \h 23A.2 - Public Certificate extraction for eSAM PAGEREF _Toc71814091 \h 23A.3 - Service continuity PAGEREF _Toc71814092 \h 23A.4 - Using Microsoft's powershell commands to create and export a self-signed certificate PAGEREF _Toc71814093 \h 24Appendix B – Service Identity provisioning in eSAM PAGEREF _Toc71814094 \h 25B.1 - General PAGEREF _Toc71814095 \h 25B.2 - AD FS Components PAGEREF _Toc71814096 \h 25B.3 - eSAM Components PAGEREF _Toc71814097 \h 26Appendix C – Web API Resources PAGEREF _Toc71814098 \h 27Appendix D – Scenario 3 – Break-down and Samples PAGEREF _Toc71814099 \h 29D.1 - Sample Access Token Request PAGEREF _Toc71814100 \h 29D.2 - Sample Access Token Response PAGEREF _Toc71814101 \h 30D.4 - Access Token Request Processing at the Authorisation Server (AD FS) PAGEREF _Toc71814102 \h 361. AD FS - Confidential Client and Certificate matching (Scenarios 2 & 3) PAGEREF _Toc71814103 \h 362. AD FS Resource permission check (All scenarios) PAGEREF _Toc71814104 \h 363. AD FS Access Token provision with Service Identity Claims PAGEREF _Toc71814105 \h 36D.5 - Break-down of the Access Token Response PAGEREF _Toc71814106 \h 371. Access Token Response attributes PAGEREF _Toc71814107 \h 372. Access Token Response format PAGEREF _Toc71814108 \h 39D.6 – Using the access token in a Web API request PAGEREF _Toc71814109 \h 391. Web API Request – Authorization header PAGEREF _Toc71814110 \h 392. Access token break-down PAGEREF _Toc71814111 \h 39D.7 - Constructing the client-assertion value PAGEREF _Toc71814112 \h 421. General PAGEREF _Toc71814113 \h 422. The client-assertion header PAGEREF _Toc71814114 \h 423. The client-assertion body PAGEREF _Toc71814115 \h 444. Constructing the client-assertion value - Sample C# code PAGEREF _Toc71814116 \h 45Appendix E – Scenario 1 – Third Party Client Application – Authentication/Authorisation Flow PAGEREF _Toc71814117 \h 54Appendix F – Scenario 2 – Web Application – Authentication/Authorisation Flow PAGEREF _Toc71814118 \h 55Appendix G – Scenario 3 – Service-to-service – Authentication/Authorisation flow PAGEREF _Toc71814119 \h 56Document HistoryTable SEQ Table \* ARABIC 1 - Document HistoryVersionDateAuthorSummary of ChangesStatusAuthorised By0.19/07/2018GA2667Initial Draft Draft1.013/08/2018GA2667Post reviewFinal1.117/09/2018GA2667Clarification of certificate requirementsReleased2.020/11/2018GA2667Major revision - addition of Client Credentials GrantDetailDraft2.003/11/2020CB0305Update to certificate specification2.013/04/2021CB0305Update to table 262.007/05/2021CB0305Moved Scenario Variation for 3rd Party IT Houses to Section 42.013/05/2021SB4093Replaced the makecert description with powershell commands in Appendix A.4Trim ID: D18/6349001. Introduction1.1 GeneralThe Department of Education, Skills and Employment (the department) has made ESS available to Provider organisations via Web API Gateway.The Web API Gateway allows Service Providers, Employers and 3rd Party IT Houses to develop bespoke applications and services that interact with the department’s APIs.This gives organisations the ability to integrate ESS data and functions into their own applications and workflow.The authentication and authorisation of applications and services calling departmental APIs differs depending on the type of application, and for whom the application or service runs.The authentication scenarios implemented adhere to the OAuth 2.0 specification. Specifically:Authorization Code GrantPublic Client (Scenario 1)Confidential Client (Scenario 2)Client Credentials Grant (Scenario 3)This document describes three distinct usage scenarios and provides the following for each:A descriptive overviewPrerequisites Roles and responsibilities1.2 Scenario decision treeThe following decision tree may help organisations to decide which authentication scenario is required:1.3 Document ConventionsThe Scenario Synopsis sections of the document include sample request parameters and sample responses. The samples provided are not extensive; they are mock-ups and aim to highlight dependencies only. Please refer to the OAuth 2.0 specification where required.1.4 Intended AudienceIT contacts of organisations subscribing to the Departments API Gateway.1.5 ReferencesOfficial Standardhttps://tools.ietf.org/html/rfc6746A Guide to OAuth 2.0 Grantshttps://alexbilbie.com/guide-to-oauth-2-grants/This easily digestible article details the OAuth 2.0 conventions and grant types implemented by the API Gateway.1.6 Contact DetailsAPI Product ManagerContact the API Product Manager at the following address:APIGatewayManagement@dese.gov.au1.7 Prerequisites for all scenariosCheck Appendix C – Web API Resources for details on values for Audience, Public Client Id, Redirect URL 2. Scenario 1 – Third Party Client Application2.1 Brief DescriptionA third party client application requires access to departmental APIs.The third party client application can exist anywhere and on any device. The application could reside on a user’s mobile phone, for example.2.2 Scenario CharacteristicsTable SEQ Table \* ARABIC 3 - Scenario 1 characteristicsItemDescriptionScenario NameThird Party Client ApplicationApplication/Service Location(Authorisation Code Grant with Public Client)Application/Service LocationAnywhere and on any deviceAuthorisation ImplementationOAuth 2.0 OAuth 2.0 Grant TypeAuthorisation Code GrantOAuth 2.0 Client TypePublic ClientResource Owner (Who authenticates?)End-userAuthorize endpoint https://auth.dis.gov.au/adfs/oauth2/authorizeToken endpointhttps://auth.dis.gov.au/adfs/oauth2/token2.3 Scenario SynopsisAn end-user uses a third-party application that may be on any device (a mobile phone for example).At some point in the application workflow, the application needs to access departmental APIs to provide functions and data in the context of the end-user.The application requests an authorisation code (GET request to authorize endpoint).Table SEQ Table \* ARABIC 4 - Authorize request attributesAuthorize Request AttributeValue/DescriptionresourceThe identifier for the Web API resource requested.This resource value is used as the audience value in the access token. The value needs to be URL encoded.?See Appendix C – Web API Resources.client_idThe Client Id registered at the Authorisation Server. See Appendix C - Web API Resourcesresponse_typecoderedirect_uriThe Redirect URL. This is the URL the application must intercept to extract the authorisation code. Table 5 – Sample (abbreviated) request formatGET https://sample.token.provider/adfs/oauth2/authorize?resource=sample%3Aapi%3Aresource&client_id=6fc1f0a2-9800-5d72-ad2f-1e5e05e7033f&response_type=code&redirect_uri=https%3A%2F%2Flocalhost%3A24563%2Fsomething%2Fim%2Flistenting%2FtoAt this point if the end-user is unauthenticated, the authorisation server redirects the user to a Security Token Service. The user supplies their credentials to authenticate. The authorisation server responds with a redirect to the Public Client URI with the authorisation code.Table 6 - Sample (abbreviated) response formatHTTP/1.1 302 FoundLocation: <redirect_uri>/code=<authorisation_code>The application requests an access token (POST request to token endpoint).Table 7 – Access Token request attributesAccess Token Request AttributeValue/Description?resourceThe identifier for the Web API resource requested.This resource value is used as the audience value in the access token.See Appendix C – Web API Resources.client_idThe Client Id registered at the Authorisation Server. See Appendix C - Web API Resources??grant_typeauthorization_codecodecoderedirect_uriThe Public Client Redirect URI. This is the URI the application must intercept to extract the authorisation code.Table 8 - Sample (abbreviated) request formatPOST https://sample.token.provider/adfs/oauth2/token{resource:"sample%3Aapi%3Aresource",client_id:"6fc1f0a2-9800-5d72-ad2f-1e5e05e7033f",grant_type:"authorization_code",code:"<authorization_code>",redirect_uri:"https://localhost:24563/something/im/listenting/to" }The authorisation server responds. The access_token and refresh_token are JSON tokens contained in JSON serialised data in the response body.Table 9 - Sample (abbreviated) response formatHTTP/1.1 200 OK{headers, etc.} {“access_token”:<access_token>,”token_type”:”bearer”,“expires_in”:<expire_time>,“resource”:<resource>,“refresh_token”:<refresh_token>,“refresh_token_expires_in”:<refresh_token_expire_time>}In production the access_token includes the claims as stored in the eSAM Identity System for the user who authenticated to the STS.Note: The end-user claims (including application roles assigned by the OSC in eSAM) determine the data and functions accessible via the API. I.e. The user may only access the data and functions they can normally access when using ESS Web directly.The application uses the access_token to populate the authorisation header of any call to the departmental API.Table 10 - Sample (abbreviated) API Call formatGET <API resource endpoint> HTTP/1.1Authorization: Bearer <access_token>As required, the client may use the refresh_token to request another access_token without re-supplying credentials to the STS.Table 11 - Refresh Token request attributesRefresh Token Request AttributeValue/DescriptionresourceThe identifier for the Web API resource requested.This resource value is used as the audience value in the access token.See Appendix C – Web API Resources.client_idThe Client Id registered at the Authorisation Server. See Appendix C - Web API Resources.grant_typerefresh_tokenrefresh_token<refresh_token>Table 12 - Sample (abbreviated) request formatPOST https://sample.token.provider/adfs/oauth2/token{resource:"sample:api:resource",client_id:"6fc1f0a2-9800-5d72-ad2f-1e5e05e7033f",grant_type:"refresh_token",refresh_token:"<refresh_token>",redirect_uri:"https://localhost:24563/something/im/listenting/to" }The authorisation server responds with a new access_token.Table 13 - Sample (abbreviated) response formatHTTP/1.1 200 OK{headers, etc} {“access_token”:<access_token>”.”token_type”:”bearer”,“expires_in”:<expire_time>,“resource”:<resource>}3. Scenario 2 – Web Application3.1 Brief DescriptionAn organisation’s web application requires access to departmental APIs.The web application resides on the organisation’s network and needs to access departmental APIs in the context of the end-user.3.2 Scenario CharacteristicsTable 14 - Scenario 2 characteristicsItemDescriptionScenario NameWeb Application(Authorization Code Grant with Confidential Client)Application/Service LocationOrganisation NetworkAuthorisation ImplementationOAuth 2.0 OAuth 2.0 Grant TypeAuthorisation Code GrantOAuth 2.0 Client TypeConfidential ClientResource Owner (Who authenticates?)End-userAuthorize endpoint https://auth.dis.gov.au/adfs/oauth2/authorizeToken endpointhttps://auth.dis.gov.au/adfs/oauth2/token3.3 Scenario SynopsisAn end-user uses an organisation’s web-application.At some point in the application workflow, the application needs to integrate with departmental APIs to provide functions and data in the context of the end-user.The application requests an authorisation code (GET request to authorize endpoint).Table 15 - Authorize request attributesAuthorize Request Attribute?Value/DescriptionresourceThe identifier for the Web API resource requested.?This resource value is used as the audience value in the access token. ?The value needs to be URL encoded.??See Appendix C – Web API Resources.?client_idThe value is a GUID, and is provided to the IT contacts of the organisation after they submitted the Service Idendity Access (ACD) Request form.?See Appendix B – Service Identity provisioning in eSAM.response_typecoderedirect_uriThe Redirect URL. The URL must match the one provided on the ACD form.See Appendix B – Service Identity provisioning in eSAM.Table 16 - Sample (abbreviated) request formatGET https://sample.token.provider/adfs/oauth2/authorize?resource=sample%3Aapi%3Aresource&client_id=6fc1f0a2-9800-5d72-ad2f-1e5e05e7033f&response_type=code&redirect_uri=https%3A%2F%2Fmywebsite.com%2FlogincallbackAt this point if the end-user is unauthenticated, the authorisation server redirects the user to a Security Token Service. The user supplies their credentials to authenticate. The authorisation server responds with a redirect to the Confidential Client URI with the authorisation code.Table 17 - Sample (abbreviated) response formatHTTP/1.1 302 FoundLocation: <redirect_uri>/code=<authorisation_code>The user’s browser should follow the redirect back to the organisation’s web application.The application requests an access token (POST request to token endpoint). The request sends a Confidential Client Id and client_assertion.Table 18 – Access Token request attributesAccess Token Request Attribute?Value/DescriptionresourceThe identifier for the Web API resource requested.?This resource value is used as the audience value in the access token.?See Appendix C – Web API Resources.client_idThe value is a GUID, and is provided to the IT contacts of the organisation after they submitted the Service Idendity Access (ACD) Request form.See Appendix B – Service Identity provisioning in eSAM.grant_typeauthorization_codecodecodeclient_assertion_typeThis value is used to inform AD FS what type of assertion is being provided to assert the credential. This value is URL encoded, and must be supplied verbatim.The non-encoded value is:urn:ietf:params:oauth:client-assertion-type:jwt-bearerclient_assertion<assertion_value> is the client_assertion token (JWT) generated by the Client Application. It includes the signature using the Private Key for the certificate uploaded via eSAM.The client_assertion provides evidence to the authorisation server ADFS, that the creator of the assertion has access to the private key, and the private key corresponds to the public key uploaded via ESAM when the Service Identity was provisioned. The Service Identity is bound to the client_id.See D.7 - Constructing the client-assertion value.redirect_uriThe Redirect URL. The URL must match the one provided on the ACD form.?See Appendix B – Service Identity provisioning in eSAM.Table 19 - Sample (abbreviated) request formatPOST https://sample.token.provider/adfs/oauth2/token{resource:"sample%3Aapi%3Aresource",client_id:"6fc1f0a2-9800-5d72-ad2f-1e5e05e7033f",grant_type:"authorization_code",code:"<authorization_code>",client_assertion_type:"urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer",client_assertion:"eyJhbGciOiJIUzI1NiIsIng1dCI6ImJtOTBJR0VnZEdoMWJXSnlhVzUwIn0.eyJhdWQiOiJodHRwczovL3NhbXBsZS50b2tlbi5wcm92aWRlci9hZGZzL29hdXRoMi90b2tlbiIsImlzcyI6IjZmYzFmMGEyLTk4MDAtNWQ3Mi1hZDJmLTFlNWUwNWU3MDMzZiIsInN1YiI6IjZmYzFmMGEyLTk4MDAtNWQ3Mi1hZDJmLTFlNWUwNWU3MDMzZiIsIm5iZiI6MSwiZXhwIjoyMDUzMDYxNjc2LCJqdGkiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ.9uYe2RuJnQWuvXfaj0qbchcT3DCB3u-TNx8bIoSWoc8",redirect_uri:"https://mywebsite.com/logincallback" }The authorisation server responds. The access_token and refresh_token are JSON tokens contained in JSON serialised data in the response body.Table 20 - Sample (abbreviated) response formatHTTP/1.1 200 OK{headers, etc.} {“access_token”:<access_token>,”token_type”:”bearer”,“expires_in”:<expire_time>,“resource”:<resource>,“refresh_token”:<refresh_token>,“refresh_token_expires_in”:<refresh_token_expire_time>}In production the access_token includes the claims as stored in the eSAM Identity System for the user who authenticated to the STS.Note: The end-user claims (including application roles assigned by the OSC in eSAM) determine the data and functions accessible via the API. I.e. The user may only access the data and functions they can normally access when using ESS Web directly.The application uses the access_token to populate the authorisation header of any call to the departmental API.Table 21 - Sample (abbreviated) API Call formatGET <API resource endpoint> HTTP/1.1Authorization: Bearer <access_token>As required, the client may use the refresh_token to request another access_token without re-supplying credentials to the STS.Table 22 - Refresh Token request attributesRefresh Token Request AttributeValue/DescriptionresourceThe identifier for the Web API resource requested.This resource value is used as the audience value in the access token.See Appendix C – Web API Resources.client_idThe value is a GUID, and is provided to the IT contacts of the organisation after they submitted the Service Identity Access (ACD) Request form.The Public Client Id registered at the Authorisation Server.See Appendix B – Service Identity provisioning in eSAMgrant_typerefresh_tokenrefresh_token<refresh_token>Table 23 - Sample (abbreviated) request formatPOST https://sample.token.provider/adfs/oauth2/token{resource:"sample%3Aapi%3Aresource",client_id:"6fc1f0a2-9800-5d72-ad2f-1e5e05e7033f",grant_type:"refresh_token",refresh_token:"<refresh_token>",redirect_uri:"https://localhost:24563/something/im/listenting/to"}The authorisation server responds with a new access_token.Table 24 - Sample (abbreviated) response formatHTTP/1.1 200 OK{headers, etc.} {“access_token”:<access_token>”.”token_type”:”bearer”,“expires_in”:<expire_time>,“resource”:<resource>}4. Scenario 3 – Service-to-service4.1 Brief DescriptionAn organisation (or third party provider) service requires access to departmental APIs.The service requests an access_token directly by supplying a Confidential Client Id and a signed Client Assertion (JWT).There is no end-user to authenticate in this scenario.Please note: A detailed break-down and examples for Scenario 3 is available at REF _Ref529969343 \h \* MERGEFORMAT Appendix D – Scenario 3 – Break-down and Samples.4.2 Scenario CharacteristicsTable 25 - Scenario 3 characteristicsItemDescriptionScenario NameService-to-service(Client Credentials Grant with Confidential Client)Application/Service LocationOrganisation NetworkAuthorisation ImplementationOAuth 2.0 OAuth 2.0 Grant TypeClient Credentials GrantOAuth 2.0 Client TypeConfidential ClientResource Owner (Who authenticates?)Application with Confidential ClientClient Credentials ProviderApplication via Confidential Client Id and client_assertionAuthorize endpoint Not usedToken endpointhttps://auth.dis.gov.au/adfs/oauth2/token4.3 Scenario SynopsisAn organisation’s service is running.At some point in the service workflow, the service needs to integrate with departmental APIs to access functions and data in the context of the Service Identity (Confidential Client).The Service Identity is a non-user identity defined to the department via eSAM. eSAM correlates the Service Identity with the Confidential Client Id registered in the authorisation server (AD FS).As there is no end-user to authenticate in this scenario, the service requests an access_token directly. The service requests an access token (POST request to token endpoint). The request sends a Confidential Client Id and client_assertion.Table 26 – Access Token Request attributesAccess Token Request Attribute?Value/DescriptionresourceThe identifier for the Web API resource requested.This resource value is used as the audience value in the access token.See Appendix C – Web API Resources.client_idThe value is a GUID, and is provided to the IT contacts of the organisation after they submitted the Service Idendity Access (ACD) Request form.See Appendix B – Service Identity provisioning in eSAM.grant_type"client_credentials"codecodeclient_assertion_typeThis value is used to inform AD FS what type of assertion is being provided to assert the credential. This value is URL encoded, and must be supplied verbatim.The non-encoded value is:urn:ietf:params:oauth:client-assertion-type:jwt-bearerclient_assertion?<assertion_value> is the client_assertion token (JWT) generated by the Client Application. It includes the signature using the Private Key for the certificate uploaded via eSAM.The client_assertion provides evidence to the authorisation server ADFS, that the creator of the assertion has access to the private key, and the private key corresponds to the public key uploaded via ESAM when the Service Identity was provisioned. The Service Identity is bound to the client_id.See D.7 - Constructing the client-assertion value.Table 27 - Sample (abbreviated) request formatPOST https://sample.token.provider/adfs/oauth2/token{resource:"sample%3Aapi%3Aresource",client_id:"6fc1f0a2-9800-5d72-ad2f-1e5e05e7033f",client_assertion_type:"urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer",client_assertion:"eyJhbGciOiJIUzI1NiIsIng1dCI6ImJtOTBJR0VnZEdoMWJXSnlhVzUwIn0.eyJhdWQiOiJodHRwczovL3NhbXBsZS50b2tlbi5wcm92aWRlci9hZGZzL29hdXRoMi90b2tlbiIsImlzcyI6IjZmYzFmMGEyLTk4MDAtNWQ3Mi1hZDJmLTFlNWUwNWU3MDMzZiIsInN1YiI6IjZmYzFmMGEyLTk4MDAtNWQ3Mi1hZDJmLTFlNWUwNWU3MDMzZiIsIm5iZiI6MSwiZXhwIjoyMDUzMDYxNjc2LCJqdGkiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ.9uYe2RuJnQWuvXfaj0qbchcT3DCB3u-TNx8bIoSWoc8",grant_type:"client_credentials", }The authorisation server responds. The access_token is a JSON token contained in JSON serialised data in the response body. A client credentials grant does not issue a refresh_token.Table 28 - Sample (abbreviated) response formatHTTP/1.1 200 OK{headers, etc.} {“access_token”:<access_token>,”token_type”:”bearer”,“expires_in”:<expire_time>,“resource”:<resource>}In production the access_token includes the claims as stored in the eSAM Identity System, for the Service Identity.Note: The Confidential-Client/Service-Identity is the ESS User in this scenario. In this case, the Service Identity claims (including application roles assigned by the OSC in eSAM) determine the data and functions accessible via the API. The OSC must ensure the Service Identity has the roles required for the service to function as expected.The service uses the access_token to populate the authorisation header of any call to the departmental API.Table 29 - Sample (abbreviated) API Call formatGET <API resource endpoint> HTTP/1.1Authorization: Bearer <access_token>4.4 Scenario Variation for 3rd Party IT HousesThe variation described in this section allows the 3rd Party IT House to deal with only one Service Identify if they choose to do so. The 3rd Party IT House aims to get the Service Provider/Employer end-user to authenticate to the Department’s token service, then to get a ‘code’ (specifically for the 3rd Party IT House Client Identifier) from ADFS. After the Service Provider/Employer end-user has successfully obtained the code from the ADFS authorise endpoint, the code is sent (usually via HTTP redirect) to the 3rd Party IT House.The 3rd Party IT House makes a request to the ADFS token endpoint for the end-user’s Access token. The request includes the code (of the Service Provider/Employer end-user), the 3rd Party IT House Client Identifier, and a signed JWT proving that the sender of the request knows the private key of the certificate securing the client identifier.The resultant end-user’s Access token contains the claims of the Service Provider/Employer end-user who authenticated. The end-user’s Access token can then be used to access the API.The 3rd Party IT House would/could not successfully act to call API if it had authenticated as itself. That is, if the Service Identity was used for a machine-to-machine type call (Scenario 3), the resultant claims in the token would be ‘unacceptable’ to the API.In summary, as long as the Service Provider/Employer end-user has requested the code from the authorise endpoint for the 3rd Party IT House’s Client Identifier, the code can be used by the 3rd Party IT House to retrieve a token. The diagram below describes this process and should be read in conjunction with the diagram in Appendix F which describes scenario in detail.6. GlossaryTable 30 – Glossary of Terms, Acronyms and AbbreviationsTerm/AcronymDescription3rd Party IT HousesNon-contracted organisations that provide IT services to Service Providers and/or to EmployersADFSActive Directory Federation Services. Uses a claims-based access control authorisation model, to provide single sign-on to users of applications across organisational boundaries.ADWAbbreviated Data Warehouse. ADW is a generic database containing codes, code types, relationships and relationship types for use by departmental systems.APIApplication Programming Interface. A set of clearly defined methods of communication between various components.Confidential ClientA (software) client that is capable of keeping a secret confidential to the world. For example, a web application.EmployersNon-contracted organisations that consume Vacancy Services.eSAMEmployment Security Access ManagementESS applicationThe following applications are included in the ESS application context: ESS Web, CDP, ESS SmartClient, ECSN Provider Portal and ES Reporting.ESS User IDThe username that applications such as ESS Web and CDP use to identify the user. Not used to logon to eSAM or ESS applications, but is used to record updates made by the user in Jobs and Small Business applications. Registered Username and ESS Username are linked in the eSAM application. HTTPHypertext Transfer ProtocolHTTPSSecure HTTP. An encrypted version of HTTP using Transport Layer Security (TLS) or formerly SSL (Secure Sockets Layer)JWTJavaScript Object Notation (JSON) Web Token. A signed and self-contained standard for securely transmitting information between parties.OSCOrganisation Security ContactPublic ClientA (software) client that is not capable of keeping a secret confidential to the world. For example, a desktop application.Service ProvidersContracted organisations that provide employment services according to a deed.STS/Security Token ServiceA service where the user can enter credentials and the service emits a signed set of claims for the ADFS authority to consume. The ADFS authority trusts the claims for the user emitted by the STS, as long as the signature is valid.Service IdentityA non-user identity in eSAM defined primarily to enable background service-to-service authentication.URIUniform Resource IdentifierURLUniform Resource LocatorAppendix A – Certificate and encoding specificationA.1 - Certificate specificationThe Certificates generated by the Organisation must meet the following specification:The certificate Subject Name must be the same as the Issuer NameA.2 - Public Certificate extraction for eSAMCertificate data supplied for creating and maintaining Service Identities must meet the following specification:The extracted certificate data must be a Base64 encoded extract of the Public certificate Failure to meet the certificate and encoding specifications, results in failure when attempting to store the certificate data via eSAM.A.3 - Service continuityFor service continuity, eSAM allows up to two certificates to be supplied:At least one current certificate is required for service authorisationCertificates supplied must span the current date. I.e. The certificate start-date must be less than the current date, and the certificate end-date (expiry-date) must be greater than the current date.The intention is that new certificate data is supplied prior to the expiry of the current certificate. Please refer to the diagram below: Figure SEQ Figure \* ARABIC 1 - Multiple certificates for continuityThe system deletes data for certificates that have expired.A.4 - Using Microsoft's powershell commands to create and export a self-signed certificateMicrosoft’s powershell commands can be used for creating and exporting a self-signed certificate. Provided below is an example powershell command to create a new self-signed certificate and extend the end date by 5 years:Table 31 - Powershell command example - New-SelfSignedCertificateNew-SelfSignedCertificate -DnsName "sample.cer" -CertStoreLocation "cert:\LocalMachine\My" -NotAfter (Get-Date).AddYears(5)The following table contains the export certificate cmdlet to export a certificate store to a file:Table 32 - Powershell cmdlet example - Export-Certificate$cert = Get-ChildItem -Path cert:\LocalMachine\My\66581D94A90360884028B84208369D0B943D0C3DExport-Certificate -Cert $cert -FilePath sample.cerThe private key is not included in the export. If more than one certificate is being exported, then the default file format is SST. Otherwise, the default format is CERT. Use the?Type?parameter to change the file format.This example exports a certificate to the file system as a DER-encoded?.cer?file without its private key.The following table contains the certutil command to convert the certificate to Base 64 format:Table 33 - Powershell command example - certutilcertutil -encode sample.cer base64cer.cerSee screenshot below:Appendix B – Service Identity provisioning in eSAMB.1 - GeneralThe provisioning of the Service Identity occurs via the department’s security access management system, eSAM. The OSC or Application Support Security staff acting as OSC, are responsible for all of the creation and maintenance aspects of Service Identities via eSAM. They should refer to the eSAM – Manage Service Identities – OSC User Guide, available as EAKB article KE3885, for specific eSAM functions relating to Service Identities.B.2 - AD FS ComponentsWhen a Service Identity is created in eSAM, the following attributes are stored at the Authorisation Server (AD FS):The Confidential Client IdThis is a Globally Unique Identifier (GUID).Depending on the context, this is sometimes referred to as a:Client IdPrivate Client IdService Identity A public certificateThis is extracted from the certificate created and stored at the organisation. This is supplied to the OSC for uploading via eSAM.Please see REF _Ref525729052 \h \* MERGEFORMAT Appendix A – Certificate and encoding specification.A Redirect URIDepending on the context, this is sometimes referred to as the:Redirect URLConfidential Client Redirect URLReply URIThis is only used for the OAuth 2.0 Confidential Client Authorization Code Grant (Scenario 2), and provides a redirection address for the Authorisation Code response.Web API Resource permissionsThe Server Application created in ADFS (via the creation process in eSAM), grants permissions to one or more Web API Resources. For example:‘urn:api:webapi:acd’ ‘urn:api:ess’‘urn:api:webapi:acs’ The permission allows the server application to generate access tokens targeting only permitted resources as an audience.The Access Token request from organisation or third party, specifies the exact resource requiring an access token. AD FS must match the specified resource with one of the resources permitted, before an access token is granted.When AD FS issues an access token, it uses the requested resource name as the audience value. The audience value in the access token allows the consumer of the access token (the forwarding handler, for example) to make authorisation decisions based on the audience of the signed access token.B.3 - eSAM ComponentsThe OSC assigns application roles (claims) to the Service Identity using eSAM functions.Upon creation of the Access Token via relying party rules, AD FS queries eSAM to retrieve the application roles that are applicable to the Service Identity. The roles are presented as claims in the access token, and allow relying party applications to make appropriate authorisation decisions.Appendix C – Web API ResourcesEnvironmentProductAudiencePublic Client IDRedirect URLNotesUnder ConstructionUnder construction---No authentication is requiredVacancy Services – Under Construction---No authentication is requiredPre releasePre-Release - Third Party Client Applicationurn:api:webapi:acdee868cf8-cbc1-4b4b-9de2-ae8426e86d08https://localhost:9999/callbackPre-Release - Web ApplicationPre-Release - Service to ServiceVacancy Services – Pre-Release - Third Party Client Applicationee868cf8-cbc1-4b4b-9de2-ae8426e86d08https://localhost:9999/callbackVacancy Service – Pre-Release - Web ApplicationVacancy Services – Pre-Release - Service to ServiceProductionLive - Third Party Client Applicationurn:api:ess7172b736-7239-4b1c-8529-046ab0fc091fhttps://localhost:9999/callbackLive - Web ApplicationLive - Service to ServiceVacancy Services – Live - Third Party Client Applicationurn:api:webapi:acs8de6f07e-8e0a-4303-94c8-ab059669ed7dhttps://localhost:9998/callbackVacancy Service – Live - Web ApplicationVacancy Services – Live - Service to ServiceGeospacial-Services-Liveurn:api:webapi:acs8de6f07e-8e0a-4303-94c8-ab059669ed7dhttps://localhost:9998/callbackAppendix D – Scenario 3 – Break-down and SamplesD.1 - Sample Access Token RequestThe following is an HTTP Request showing the POST request to the token endpoint. This request directly maps to flow #1 in REF _Ref529805915 \h \* MERGEFORMAT Error! Reference source not found..Note: Line-breaks exist for clarityScenario 3 - Sample Access Token RequestPOST https://auth.dis.gov.au/adfs/oauth2/token HTTP/1.1Accept: text/html, application/json, application/xhtml+xml, image/jxr, */*User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; rv:11.0) like GeckoContent-Type: text/htmlContent-Language: en-AUHost: sample.domain.nameContent-Length: 932Expect: 100-continueConnection: Keep-Aliveresource=urn%3aapi%3aess%3atest&client_id=e1ae3fdf-a037-4093-b5fa-c467b57f6f33&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Im1EVU5aWG1tTzU0d2hhMm9RQ2I2WVhuU2dJYyJ9.eyJhdWQiOiJodHRwczovL3N0cy5kZXYuY29uc3RydWN0aW9uLmVuZXQvYWRmcy9vYXV0aDIvdG9rZW4iLCJpc3MiOiJlMWFlM2ZkZi1hMDM3LTQwOTMtYjVmYS1jNDY3YjU3ZjZmMzMiLCJzdWIiOiJlMWFlM2ZkZi1hMDM3LTQwOTMtYjVmYS1jNDY3YjU3ZjZmMzMiLCJuYmYiOjE1MzkyOTk5NDIsImV4cCI6MTUzOTMwMDU0MiwianRpIjoiMDA4NjhjODMtNmE1Yi00NmViLWFkZTUtZDA5YTJlZGJmNzE0In0.muHgCU8gXvSz4OPrs3GsKmWGdaIfxjSgAcVMMbAGBJLgYKAwvLwvo2DFDkJi2kjLDmaIusjVcnLNsSyqtNQSHP7OuZha-QapbSdCSVkkC9o7hutz-qljZLpcwe_QOtbq9h0jslJ3CDDmVJbWMh0VjlxaEPxRVqbvKIX3NRiuqis14qM4p10ZpajFQhGGtPTtjzt2M3wGmsDhEpem6CgJNWBzBm_P8SZ72inOpjiYwcr3YbjGv_gOVzX4fAHHb9-Rb_-CclC4Fq-J2Cpi5IIcvSZAqpsgE7RoV5uRlouXG1K2cL0invjfXsrZqFz2NddRnMNH6Cf0vi4tyyfvji00uQ&grant_type=client_credentialsclient-assertion format legend: Base64 header.Base64 body.Base64 signatureD.2 - Sample Access Token ResponseThe following is an HTTP Response showing the subsequent successful (HTTP 200) response with the access token in the response body as a JSON payload. This response directly maps to flow #2 in REF _Ref529805915 \h \* MERGEFORMAT Error! Reference source not found..Note: Line-breaks exist for clarityScenario 3 - Sample Access Token Request ResponseHTTP/1.1 200 OKCache-Control: no-storePragma: no-cacheContent-Length: 2137Content-Type: application/json;charset=UTF-8Server: Microsoft-HTTPAPI/2.0Date: Thu, 11 Oct 2018 23:19:02 GMTpath=/; Httponly; SecureX-AppDelivery: blahX-DeliveredBy: x.x.x.x{"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImVNSUU1a3M5eDZoeWhQSkNSa3pLUC0zSVNmdyJ9.eyJhdWQiOiJ1cm46YXBpOmVzczp0ZXN0IiwiaXNzIjoiaHR0cDovL3N0cy5kZXYuY29uc3RydWN0aW9uLmVuZXQvYWRmcy9zZXJ2aWNlcy90cnVzdCIsImlhdCI6MTUzOTI5OTk0MiwiZXhwIjoxNTM5MzAwMDYyLCJodHRwOi8vd3d3LmRlZXdyLmdvdi5hdS8yMDE4LzAzL2VzYW0vcHJpbWFyeXBob25lbnVtYmVyIjoiMDQwNDA0MDQwNCIsImh0dHA6Ly93d3cuZGVld3IuZ292LmF1LzIwMTcvMDIvZXNhbS91c2VyZGVjbGFyYXRpb25hY2NlcHRlZCI6IjAiLCJodHRwOi8vd3d3LmRlZXdyLmdvdi5hdS8yMDE3LzAyL2VzYW0vdXNlcmFwcGxpY2F0aW9uYWNjb3VudGd1aWQiOiI4NTdEMUZGMy1DOThGLTQyNTQtOTkxRS0yNjFENzRERDUwMzkiLCJodHRwOi8vd3d3LmRlZXdyLmdvdi5hdS8yMDE3LzAyL2VzYW0vY29yZWlkZW50aXR5ZW5hYmxlZCI6IjEiLCJodHRwOi8vd3d3LmRlZXdyLmdvdi5hdS8yMDE3LzAyL2VzYW0vYXBwbGljYXRpb25hY2NvdW50ZW5hYmxlZCI6IjEiLCJmYW1pbHlfbmFtZSI6IkdsZW5uQ2xhcmtlIiwidW5pcXVlX25hbWUiOiJDQlZWSkYyMiIsImdpdmVuX25hbWUiOiJTZXJ2aWNlIiwiZW1haWwiOiJnbGVubmNsYXJrZXNlcnZpY2VAam9icy5nb3YuYXUiLCJodHRwOi8vZGVld3IuZ292LmF1L2VzLzIwMTgvMDYvY2xhaW1zL3NlcnZpY2VpZGVudGl0eSI6IlkiLCJodHRwOi8vZGVld3IuZ292LmF1L2VzLzIwMTEvMDMvY2xhaW1zL29yZyI6IkRFUFQiLCJodHRwOi8vZGVld3IuZ292LmF1L2VzLzIwMTEvMDMvY2xhaW1zL2xhc3RMb2dvbkRhdGVUaW1lU3RhbXAiOiIiLCJodHRwOi8vZGVld3IuZ292LmF1L2VzLzIwMTEvMDMvY2xhaW1zL2RlZmF1bHRzaXRlIjoiVVNSUyIsImh0dHA6Ly9kZWV3ci5nb3YuYXUvZXMvMjAxMS8wMy9jbGFpbXMvYmFzZXJvbGUiOiJOSUwiLCJmb3J3YXJkZWRjbGllbnRpcCI6IjE2NS4xMi4yMDEuMTkxIiwiYXV0aG1ldGhvZCI6WyJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvYXV0aGVudGljYXRpb25tZXRob2QvdGxzY2xpZW50IiwiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW50aXR5L2F1dGhlbnRpY2F0aW9ubWV0aG9kL3g1MDkiXSwiYXBwdHlwZSI6IkNvbmZpZGVudGlhbCIsImFwcGlkIjoiZTFhZTNmZGYtYTAzNy00MDkzLWI1ZmEtYzQ2N2I1N2Y2ZjMzIiwiYXV0aF90aW1lIjoiMjAxOC0xMC0xMVQyMzoxOTowMi45MzBaIiwidmVyIjoiMS4wIn0.qxW-x6gGYKZFeFHWbxWlMBlERue9IM_KiFcg0sMfYcNmx94Rqkw_FU6HPYjhK1q1LM_mJhrnUDJKgCjc1F2M_8fpFOl8KGvHo6kU-6Nsnv_zlZY4xzwWKGYfz15Wys79SPh-QTs4g9NtgaM5f8Sv6iVNEK_ZOGg8XyWT3i5Y0PArbI_7RCgnggBfOAVvwrSUSjmcXBuVBh_Xh9a92dy9LG396GFnqGm5NLH7hPea96FQwDM4ttZ8mgKlApXPPt8IimNimhVCfFegfdMsxSPW34jO7Wo17bMdj0bV0fYCNIJaoYhjqAu4Ksuw7AfndWf2ysXdNNw_eSaMRYW2R53FdQ","token_type":"bearer","expires_in":120}Access token format legend: Base64 Header.Base64 Body.Base64 SignatureD.3 - Break-down of the Access Token RequestThe attributes for an access token request for a Client Credentials Grant with Confidential Client are described in the following table:Table 33 - Scenario 3 - Access Token Request attributesAccess Token Request AttributeValue/DescriptionExampleresourceThe identifier for the Web API resource requested (AKA. Relying Party Identifier). The value must match the resource registered at the Authorisation Server (AD FS) and the API Gateway.The client_id must have the access permission defined in the ADFS Web API resource. This resource value is used as the audience value in the access token. This allows the Web API to authorise itself based on whether AD FS signed the access token specifically for itself. The value needs to be URL encoded.See REF _Ref529892752 \h \* MERGEFORMAT Appendix C – Web API Resources.urn%3aapi%3aess%3atestclient_idThe Confidential Client Id (aka. Private Client Id) registered at the Authorisation Server (AD FS)This is the identifier that AD FS uses to identify the relevant server application object. The value is a GUID, and is provided to the organisation as an output of the Service identity provisioning process in ESAM. See REF _Ref529968003 \h \* MERGEFORMAT Appendix B – Service Identity provisioning in eSAM.e1ae3fdf-a037-4093-b5fa-c467b57f6f33client_assertion_typeThis value is used to inform AD FS what type of assertion is being provided to assert the credential. This value is URL encoded, and must be supplied verbatim.The non-encoded value is:urn:ietf:params:oauth:client-assertion-type:jwt-bearerurn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearerclient_assertion<assertion_value><assertion_value> is the client_assertion token (JWT) generated by the Client Application. It includes the signature using the Private Key for the certificate uploaded via eSAM.The client_assertion provides evidence to the authorisation server ADFS, that the creator of the assertion has access to the private key, and the private key corresponds to the public key uploaded via ESAM when the Service Identity was provisioned. The Service Identity is bound to the client_id.See REF _Ref529968582 \h \* MERGEFORMAT D.7 - Constructing the client-assertion value.Format = <header>.<body>.< signature>Note: The header, body and signature elements must be Base64 URL encoded.grant_typeThe type of grant being requested. The value must be provided verbatim.client_credentialsThe request attributes in the context of a POSTed HTTP access token request follow:Note: Line-breaks exist for clarityScenario 3 - Access Token Request attributes and values in contextresource=urn%3aapi%3aess%3atest&client_id=e1ae3fdf-a037-4093-b5fa-c467b57f6f33&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Im1EVU5aWG1tTzU0d2hhMm9RQ2I2WVhuU2dJYyJ9.eyJhdWQiOiJodHRwczovL3N0cy5kZXYuY29uc3RydWN0aW9uLmVuZXQvYWRmcy9vYXV0aDIvdG9rZW4iLCJpc3MiOiJlMWFlM2ZkZi1hMDM3LTQwOTMtYjVmYS1jNDY3YjU3ZjZmMzMiLCJzdWIiOiJlMWFlM2ZkZi1hMDM3LTQwOTMtYjVmYS1jNDY3YjU3ZjZmMzMiLCJuYmYiOjE1MzkyOTk5NDIsImV4cCI6MTUzOTMwMDU0MiwianRpIjoiMDA4NjhjODMtNmE1Yi00NmViLWFkZTUtZDA5YTJlZGJmNzE0In0.muHgCU8gXvSz4OPrs3GsKmWGdaIfxjSgAcVMMbAGBJLgYKAwvLwvo2DFDkJi2kjLDmaIusjVcnLNsSyqtNQSHP7OuZha-QapbSdCSVkkC9o7hutz-qljZLpcwe_QOtbq9h0jslJ3CDDmVJbWMh0VjlxaEPxRVqbvKIX3NRiuqis14qM4p10ZpajFQhGGtPTtjzt2M3wGmsDhEpem6CgJNWBzBm_P8SZ72inOpjiYwcr3YbjGv_gOVzX4fAHHb9-Rb_-CclC4Fq-J2Cpi5IIcvSZAqpsgE7RoV5uRlouXG1K2cL0invjfXsrZqFz2NddRnMNH6Cf0vi4tyyfvji00uQ&grant_type=client_credentialsclient-assertion format legend: Base64 header.Base64 body.Base64 signatureD.4 - Access Token Request Processing at the Authorisation Server (AD FS)1. AD FS - Confidential Client and Certificate matching (Scenarios 2 & 3)Upon receipt of the access token request, ADFS checks that the client_id in the request is associated with an ADFS Server Application, and that the server application has been defined as a Confidential Client. ADFS dereferences the certificate from the request (via the base64 encoded hash value), and tries to find the certificate in the Certificates’ Collection for the identified server application. If the certificate is found, the signature for the signed assertion can be validated.Note: To ensure certificate continuity, up to two current certificates may be uploaded via eSAM. See REF _Ref525729052 \h \* MERGEFORMAT Appendix A – Certificate and encoding specification for more detail.2. AD FS Resource permission check (All scenarios)After validating the signed assertion, ADFS checks that the server application has specifically been granted permission to issue an access token for the requested Web API Resource. A server application created to issue an access token for resource urn:api:webapi:acs will not issue an access token for a different resource (such as urn:api:ess). The access token request must specify the exact Web API resource identifier, and the client_id must be granted permission for the Web API Resource through the association with the server application.3. AD FS Access Token provision with Service Identity ClaimsADFS runs the transformation rules to build an access token containing the claims that have been stored in eSAM for the Service Identity (associated to the client_id).The claims in the access token can be used by relying parties to determine the functions and data available to the Service Identity.D.5 - Break-down of the Access Token Response1. Access Token Response attributesThe attributes for the access token response are described in the following table:Table 34 - Scenario 3 - Access Token Response attributesAccess Token Response AttributeValue/DescriptionExampleaccess_tokenThe access token represented as a JWT.<header>.<body>.<signature>This is the JWT to be used to authenticate to the target Web API. It has to be presented in the Authorization header of the API request.For example:POST https://sample.domain.name/api/foobar HTTP/1.1...Authorization: Bearer header.body.signature...Format = <header>.<body>.<signature>Note: The header, body and signature elements are Base64 URL encoded.token_typeThe type of token issued.This indicates how the access_token should be presented to the Web API for authentication. Specifically the token needs to be presented in the Authorization HTTP header of the HTTP request, as a bearer token.Bearer is interpreted to mean ‘Give access to the bearer of this token’.bearerexpires_inThe number of seconds for which the access token is valid, from time of issue.For example, a value of 120 means the token is valid for 2 minutes after the time of issue.1202. Access Token Response formatThe token response body is in JSON format as follows:Scenario 3 - Access Token Response attribute and value format{"access_token":"<Base64_encoded_header>.<Base64_encoded_body>.<signature>"&"token_type":"bearer"&"expires_in":number_of_seconds_from_issue}D.6 – Using the access token in a Web API request1. Web API Request – Authorization headerThe access_token issued in the access token response (from AD FS) must be used in the Authorization header for the Web API request.Table 35 - Sample Web API request - Authorization header formatPOST https://sample.domain.name/api/foobar HTTP/1.1...Authorization: Bearer header.body.signature...Following the Authorization header tag, Bearer signifies the token type.Bearer is interpreted by relying parties to mean, ‘Give access to the bearer of this token’.2. Access token break-downThe following represents a readable text version of a realistic access token:Table 36 - Access Token - readable{ "typ": "JWT", "alg": "RS256", "x5t": "eZIE5ks9x6hyhPJCRkzKP-3ISfw"}.{ "aud": "urn:mvc:essweb:dev", "iss": "http://sample.domain.name/adfs/services/trust", "iat": 1428278844, "exp": 1428282444, "unique_name": "XX9999", "http://deewr.gov.au/ws/2011/03/identity/claims/displayname": "SMITH,Fred", "given_name": "Fred", "family_name": "Smith", "email": "Fred.Smith@sample.domain.name", "http://deewr.gov.au/es/2011/03/claims/generalrole": [ "EMU", "ALA", "AJS" ], "http://deewr.gov.au/es/2011/03/claims/org": "XXXX", "http://deewr.gov.au/es/2011/03/claims/site": "ZZZZ", "http://deewr.gov.au/es/2011/03/claims/baserole": "DVO", "http://deewr.gov.au/es/2011/03/claims/defaultsite": "ZZZZ", "http://deewr.gov.au/es/2011/03/claims/orgcontract": [ "EPS5", "WDC5", "JAP", "CWCA" ], "http://deewr.gov.au/es/2011/03/claims/usertype": "UserType_NONE", "http://deewr.gov.au/es/2011/03/claims/selfregistered": "False", "authmethod": "http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/windows", "auth_time": "2015-04-06T00:07:23.757Z", "ver": "1.0"}.[Signature]The access token headerThe header contains metadata about the JWT. Specifically:The token type"typ":"JWT"Signifies the token is a JSON Web Token.The cryptosystem algorithm used for signing the token"alg":"RS256"Signifies that the RSA algorithm with a SHA256 hash was used for signing the token.The certificate hash value (sometimes called a thumbprint) for the certificate that signed the token."x5t": "<cert thumbprint information>"In this case, the ADFS signing certificate is represented. This allows the Web API to validate the token was sent from ADFS. The Forwarding Handler that initially receives the Web API requests, knows how to check that ADFS signed the JWT. Additionally, the targeted Web API resource knows how to check that the JWT was signed by ADFS. The Forwarding Handler and the Web APIs have access to the Public Certificate (and key) used by ADFS to sign the JWT. The certificate hash value (thumbprint) contained in the x5t value is used to verify that the (required) ADFS certificate was used to sign the JWT.The access token bodyThe body contain some standard access token claims and other claims resulting from the ADFS relying party transformation.The standard access token body claims follow:Token audience"aud": "<audience>"The audience value is the intended audience for the access token. This value matches the resource value of the access token request. Token issuer "iss":"<issuer>"The issue value is the address of the token issuer. In this case, it is a path to ADFS.Token issued at time"iat":<nnnnnnnnnn>This is the time that the token was issued. This is also the time from which the token is valid. The time is represented as an epoch time (the number of seconds since 01/01/1970 – UTC)."exp":<nnnnnnnnnn>This is the time that the token expires. The time is represented as an epoch time (the number of seconds since 01/01/1970 – UTC).The other claims included in access token body, relate directly to the client_id (or Service Identity). These claims are retrieved from eSAM by the ADFS transformation rules when building the access token.For this scenario (Scenario 3), these claims relate to the eSAM claims and application roles assigned to the Service Identity by the OSC or Application Support acting as OSC.D.7 - Constructing the client-assertion value1. GeneralThe client_assertion is a signed JWT sent from the client system to the department’s ADFS oauth2 token (issuance) end point. The client system must create the header value and the body value in the required format, and then create a signature for that combined value (header + body). The signature is then used along with the header and body, to create the final format of the client_assertion. The signature must be created using the certificate that was uploaded via eSAM during the on-boarding (or maintenance) process.The client system holds (and has access to) the private certificate value, whereas ADFS holds the public certificate portion of that same certificate. This allows ADFS to check the signature of the JWT, and this is the fundamental basis of the authentication assertion. Theoretically no one (person nor system) holds the private certificate other than the administrator (and their notional delegate) or a server application process in the client’s domain. Therefore (in theory), only that client system can create the signature for the emitted JWT.Assuming all conversations are appropriately secured over a TLS HTTPS connection, then only the proper owner/delegate of the private certificate should be able to assert an authentication.2. The client-assertion headerThe following table describes the attributes required in the client-assertion header:Table 37 - client-assertion header attributesAttributeDescriptionalgThe cryptosystem algorithm used for signing the client-assertion token.This must be set to 'RS256'. This is the algorithm that ADFS expects. The client system must generate a signature using that algorithm.x5tThe Base64 encoded value of the certificate’s hash value {Base64(Certificate Hash)}. Please note: it is the Certificate Hash (which is a byte array) not the Certificate Thumbprint string that gets base64 encoded.This directs ADFS to the specific certificate (associated with the client_id in ADFS) that has been used to generate the signature.Certificate thumbprint versus client-assertion-header certificate identifier (x5t)The thumbprint for a certificate is a hex encoding of the certificate’s identifying hash. The hash is an array of 20 bytes. The certificate thumbprint is a hexadecimal representation of those bytes. The value in the certificate identifier (in the Access Token request client-assertion) is the Base64 encoding of the byte-array, not the base64 encoding of the thumbprint.Consider the following assertions:Certificate Hash = 20-byte Certificate Identification ArrayCertificate Thumbprint = Hex(Certificate Hash)Client-assertion Header Certificate Identifier = Base64(Certificate Hash)Base64(Certificate Hash) <> Hex(Certificate Hash) <> Base64(Certificate Thumbprint)A readable example of the client-assertion header is shown in the context of the entire client-assertion:Table 38 - client-assertion header example in context{ "alg": "RS256", "x5t": "_dfU4aBi5AJKnyTmt5ydea8mZDo"}.{ "aud": "https://sample.domain.name/adfs/oauth2/token", "iss": "58ad8d1b-43f1-43ba-88e2-91109e69283c", "sub": "58ad8d1b-43f1-43ba-88e2-91109e69283c", "nbf": 1539911125, "exp": 1539911725, "jti": "dedc0f72-5764-49f9-b2ca-0b6e00193e63"}.[Signature]3. The client-assertion bodyThe following table describes the attributes required in the client-assertion body:Table 39 - client-assertion body attributesAttributeDescriptionaudThe intended audience for client-assertion token. This must be the OAuth 2.0 token issuance endpoint in ADFS.E.g https://auth.dis.gov.au/adfs/oauth2/token (for Production)issThe issuer of the client-assertion JWT. This must be the same as the client_id in the access token request body.subThe subject of the client-assertion JWT.This must be the same as the client_id in the access token request body.nbfToken not valid before time. Represented as an epoch time (the number of seconds since 01/01/1970 - UTC)expToken not valid after time, or token expiry time. Represented as an epoch time (the number of seconds since 01/01/1970 - UTC)jtiThe JWT Id This is a unique identifier for the JWT. This value is used by ADFS for checking that each JWT is used only once. It is a nonce in this respect. Generating a new GUID for each request is necessary and sufficient.A readable example of the client-assertion body is shown in the context of the entire client-assertion:Table 40 - client-assertion body example in context{ "alg": "RS256", "x5t": "_dfU4aBi5AJKnyTmt5ydea8mZDo"}.{"aud":"https://sample.domain.name/adfs/oauth2/token","iss":"e1ae3fdf-abcd-4093-cdef-c467b57f6f33","sub":"e1ae3fdf-abcd-4093-cdef-c467b57f6f33","nbf":1540175736,"exp":1540176336,"jti":"a4a6b92c-9b4a-4c03-ab66-42d1d4886090"}.[Signature]4. Constructing the client-assertion value - Sample C# codeGeneralThe code that follows in this section, shows the creation and assembly of the required client-assertion token attributes and their values. It shows the use of the GetHash() method of the certificate object to construct the x5t value. It shows the string formatting of the Header and Body segments, and their subsequence (URL safe) Base64 encoding. The Header and Body are formatted together, and a hash of that string is generated. A crypto formatter is loaded and the hash is passed through the crypto formatter to create the signature. Finally, the signature is formatted with the header and body, and returned in the output parameter.About the codeThe C# code snippets available in this section should be able to be assembled in to a workable class library for constructing the client-assertion value.The client-assertion forms part of the access token request to be posted to the ADFS Token endpoint. A valid request will return an access_token for the target Web API resource, containing the Service Identity claims. With the exception of the ManagedSHA256SignatureDescription and CertificateHelper private classes, the remaining code contains method definitions with no container classes. They will not compile as they stand. It is expected that a developer will copy the methods, change them to suit the operating environment, and build the appropriate libraries.Comment blocks are included in some methods to describe the process and help the developer relate to the conceptual level of building the client-assertion JWT.The codeNote that some characters may have been converted by MS Word (smart quotes, hyphens)Table 41 - Sample C# code snippets - Building the client-assertion tokenusing System;using System.Collections.Generic;using System.Linq;using System.Net;using System.Net.Http;using System.Net.Http.Headers;using System.Runtime.Serialization;using System.Security.Cryptography;using System.Security.Cryptography.X509Certificates;using System.Text;using System.Web;// _context.OAuth2TokenEndPoint = "https://sample.domain.name/adfs/oauth2/token";// _context.ClientId = “a4a6b92c-9b4a-4c03-ab66-42d1d4886090”;// _context.SigningCertficateThumbprint = “98350D6579A63B9E3085ADA84026FA6179D28087”;private string GetClientAssertionValue()/*Description:- Call CertificateHelper.FindByThumbprint to find a certificate that matches a given certificate thumbprint. - Call TrySignClientAssertion to construct the client_assertion token (JWT)Requires:- Certificate Thumbprint- The Certificate Store Name- The Certificate Store Location- The Client Id (Service Identity GUID)- The Authorisation Server Token Endpoint: Production = https://auth.dis.gov.au/adfs/oauth2/tokenReturns:- client_assertion token (JWT)*/{var certficate = CertificateHelper.FindByThumbprint(_context.SigningCertficateThumbprint, StoreName.My, StoreLocation.LocalMachine);if (certficate == null) throw new ApplicationException($"Could not find the certificate with thumbprint '{_context.SigningCertficateThumbprint}' in the storename '{StoreName.My}' and storelocation '{StoreLocation.LocalMachine}'");string clientAssertionToken;if (!TrySignClientAssertion(certficate, _context.ClientId, _context.OAuth2TokenEndPoint, out clientAssertionToken))throw new ApplicationException($"Could not create the signing client assertion token to send to ADFS in the authentication request.");return clientAssertionToken;}private static class CertificateHelper/*Description:- Loops through each certificate in the certificate store to find the certificate that matches the given thumbprint. - Throws an exception is thrown if a certificate matching the thumbprint is not found.Input:- Certificate thumbprint- The Certificate Store NameReturn:- The certificate matching the thumbprint, or NULL*/The Certificate Store Location{public static X509Certificate2 FindByThumbprint(string thumbprint, StoreName storeName, StoreLocation storeLocation){var certificateStore = new X509Store(storeName, storeLocation);certificateStore.Open(OpenFlags.ReadOnly);foreach (var certificate in certificateStore.Certificates){if (certificate == null || certificate.Thumbprint == null){continue;}if (string.Equals(certificate.Thumbprint, thumbprint, StringComparison.InvariantCultureIgnoreCase)){certificateStore.Close();return certificate;}}throw new ArgumentException(string.Format("Cannot find certificate with thumbprint {0} in certificate store: {1} at location: {2} ", thumbprint, storeName, storeLocation));}}private bool TrySignClientAssertion(X509Certificate2 certificate, string clientIdentifier, string audience, out string clientAssertionToken)/* Description:Ultimately constructs the client_assertion token (JWT) in the format: <Base64 encoded Token Header>.<Base64 encoded Token Body>.<Base64 encoded Token Signature> Note: The Base64 URL Encoding method performs character replacements after the Base64 encoding, to make the string URL friendly. The method:- Replaces "+" with "-"- Replaces "/" with "_"- Replaces "=" with ""- Construct the Base64 encoded Token HeaderReadable Token Header format = {"alg":"RS256","x5t":"<Base64encodedCertificateHash>"}- The alg attribute value is set to 'RS256'. This lets the audience know that the JWT token was signed using the RSA cryptosystem algorithm with a secure 256-bit hash (SHA-256).- Construct the value of the 'x5t' attribute. Get a Base64 URL encoded version of the certificate hash. The Certificate.GetCertHash method returns a SHA-256 hash, which must then be Base64 encoded.- Base64 (URL) encode the Token Header- Construct the Base64 encoded Token BodyReadable Token Body format = {"aud":"<audience / authorisation server - OAuth 2.0 token issuance endpoint>,"iss":"<Token Issuer - Must be the same as the client_id in the request body - Private Client Id / Service Identity GUID>","sub":"<Token Subject - Must be the same as the client_id in the request body - Private Client Id / Service Identity GUID>","nbf":"<Token valid start (not before) time - epoch time>","exp","<Token valid end (expiry) time - epoch time>""jti":"<unique identifier for the JWT - new GUID>"}- The "aud" attribute value is set to the Authentication Server (AD FS) OAuth 2.0 Token endpoint- The "iss" attribute value is set to the Service Identity GUID (Client Id)- The "sub" attribute value is set to the Service Identity GUID (Client Id)- The "nbf' attribute value is set to the client_assertion token valid start (not before) time. This the current time represented as an epoch time. I.e. the number of seconds since midnight 01/01/1970 (UTC)- The "exp" attribute value is set to the client_assertion token valid-to (or expiry) time. This is set to 10 minutes greater than the nbf time. I.e. nbf + (60 * 10)- The "jti" attribute value is set to a newly generated GUID value. - Base64 (URL) encode the Token Body- Construct the Base64 encoded Token Signature- Get a HeaderBody SHA-256 hash of the "<Base64 encoded Token Header>.<Base64 encoded Token Body>"- Use the RSACryptoServiceProvider class (with hash algorithm set to SHA256) to create a Token Signature using:- The HeaderBody hash- The Certificate Private Key- Base64 (URL) encode the Token SignatureInput:- The Certificate (X509)- The Client_Id (Private Client Id/Service Identity GUID)- The Audience: The Authorisation Server Token Endpoint - https://auth.dis.gov.au/adfs/oauth2/tokenOutput:- The client_assertion token (JWT)Return:- boolean true*/{clientAssertionToken = null;// Construct the Construct the Base64 encoded Token Headervar base64EncodedCertficateHash = Base64UrlEncode( certificate.GetCertHash() );var assertionTokenHeader = "{" + $"\"alg\":\"RS256\",\"x5t\":\"{base64EncodedCertficateHash}\"" + "}";var encodedAssertionTokenHeader = Base64UrlEncode(assertionTokenHeader);// Construct the Base64 encoded Token Bodyint nbf = (int)DateTime.UtcNow.Subtract(new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc)).TotalSeconds;int exp = nbf + (60 * 10);var assertTokenBody = "{" + $"\"aud\":\"{audience}\",\"iss\":\"{clientIdentifier}\",\"sub\":\"{clientIdentifier}\",\"nbf\":{nbf},\"exp\":{exp},\"jti\":\"{Guid.NewGuid().ToString()}\"" + "}";var encodedAssertionTokenBody = Base64UrlEncode(assertTokenBody);// Construct the Base64 encoded Token Signaturevar bytesToSign = Encoding.UTF8.GetBytes($"{encodedAssertionTokenHeader}.{encodedAssertionTokenBody}");var sha256 = SHA256.Create();var hash = sha256.ComputeHash(bytesToSign);var cryptoProvider = (RSACryptoServiceProvider)certificate.PrivateKey;var cryptoDescription = new ManagedSHA256SignatureDescription();var formatter = cryptoDescription.CreateFormatter(certificate.PrivateKey);formatter.SetHashAlgorithm("SHA256");var signature = formatter.CreateSignature(hash);var tokenSignature = Base64UrlEncode(signature);// Construct the client_assertion tokenclientAssertionToken = $"{encodedAssertionTokenHeader}.{encodedAssertionTokenBody}.{tokenSignature}";return true;}private static string Base64UrlEncode(string input){return Base64UrlEncode(Encoding.UTF8.GetBytes(input));}private static string Base64UrlEncode(byte[] inputBytes){// Special "url-safe" base64 encode.return Convert.ToBase64String(inputBytes) .Replace('+', '-') .Replace('/', '_') .Replace("=", "");}private class ManagedSHA256SignatureDescription : SignatureDescription{public ManagedSHA256SignatureDescription(){KeyAlgorithm = typeof(RSACryptoServiceProvider).FullName;DigestAlgorithm = typeof(SHA256Managed).FullName;}public override AsymmetricSignatureDeformatter CreateDeformatter(AsymmetricAlgorithm key){if (key == null){throw new ArgumentNullException(nameof(key));}var deformatter = new RSAPKCS1SignatureDeformatter(key);deformatter.SetHashAlgorithm(typeof(SHA256Managed).FullName);return deformatter;}public override AsymmetricSignatureFormatter CreateFormatter(AsymmetricAlgorithm key){if (key == null){throw new ArgumentNullException(nameof(key));}var provider = (RSACryptoServiceProvider)key;var cspParams = new CspParameters();cspParams.ProviderType = 24;cspParams.KeyContainerName = provider.CspKeyContainerInfo.KeyContainerName;cspParams.KeyNumber = (int)provider.CspKeyContainerInfo.KeyNumber;if (provider.CspKeyContainerInfo.MachineKeyStore){cspParams.Flags = CspProviderFlags.UseMachineKeyStore;}cspParams.Flags |= CspProviderFlags.UseExistingKey;provider = new RSACryptoServiceProvider(cspParams);var formatter = new RSAPKCS1SignatureFormatter(provider);formatter.SetHashAlgorithm(typeof(SHA256Managed).FullName);return formatter;}}Appendix E – Scenario 1 – Third Party Client Application – Authentication/Authorisation FlowAppendix F – Scenario 2 – Web Application – Authentication/Authorisation FlowAppendix G – Scenario 3 – Service-to-service – Authentication/Authorisation flow

How do I open a file in PowerShell? To open a file using PowerShell, follow the steps given below. 1. Open the PowerShell window. You can do that on Windows by searching for it in the Start menu. Alternatively, right-click on the Start menu and select the “Windows PowerShell” option. 2. Use the below command to go to the folder where the file you want to open is located.