Skip to content
This repository was archived by the owner on Apr 27, 2021. It is now read-only.

Fabric Identity PowerShell module

Jump to bottom
Ryan Orbaker edited this page Oct 11, 2018 · 2 revisions

Installation

Powershell Gallery Link

To Install the CatalystDosIdentity module run PowerShell in administrator mode and run the following command:

Install-Module -Name CatalystDosIdentity

This installs the module locally to your machine. Default location is: C:\Program Files\WindowsPowerShell\Modules\CatalystDosIdentity

To checkout CatalystDosIdentity without installing, run the following commands:

Save-Module -Name CatalystDosIdentity -Path <path>

Navigate to the directory which contains both the CatalystDosIdentity.psd1 and CatalystDosIdentity.psm1 files and run:

Import-Module CatalystDosIdentity

CatalystDosIdentity Functions

This section covers the functions included in the CatalystDosIdentity Powerscript module.

Get-AccessToken

Used to get an access token for a specified client.

The Get-AccessToken function will return an access token string upon successful request.

Upon unsuccessful request, will return any exceptions raised.

Get-AccessToken takes the following parameters:

  • identityUrl
    • The identity url to get the access token from.
  • clientId
    • The id of the client the access token is being requested for.
  • secret
    • The secret of the client the access token is being requested for.
  • scope
    • The scope of the access token to be requested
    • Scope is an optional parameter which returns an access token for all scopes if not specified

Example Request:

Get-AccessToken -identityUrl "https://server/identity" -clientId "sample-client-id" -secret "SECrEtStrING"

Get-FabricInstallerAccessToken

Used to get an access token for the Fabric Installer client.

The Get-FabricInstallerToken function will return an access token string upon successful request.

Upon unsuccessful request, will return any exceptions raised.

Get-FabricInstallerAccessToken takes the following parameters:

  • identityUrl
    • The identity url to get the access token from.
  • secret
    • The secret of the fabric installer client.

Example Request:

Get-FabricInstallerAccessToken -identityUrl "https://server/identity" -secret "SECrEtStrING"

Get-ClientRegistration

Attempts to retrieve information about an existing identity client

Returns a client identity object. The object matches the properties from Fabric.Identity.API.Models.Client

Any exception within is raised. Specifically, if the matching client is not found, a 404 WebException is thrown.

Get-ClientRegistration takes the following Parameters:

  • identityUrl
    • The base identity url
  • clientId
    • the identifier for the client object to retrieve
  • accessToken
    • an access token previously retrieved from the identity server

Example Request:

Get-ClientRegistration -identityUrl "https://server/identity" -clientId "sample-client-id" -accessToken "eyJhbGciO"

New-ClientRegistration

Attempts to register a new identity client If successful, returns a client secret for the new client.

If the client already exists, this function updates the client attributes and resets the client secret.

Exceptions thrown in this function are wrapped, and may be access through the InnerException.

New-ClientRegistration takes the following parameters:

  • identityUrl
    • The base identity url
  • body
  • accessToken
    • An access token previously retrieved from the identity server

Example Request:

New-ClientRegistration -identityUrl "https://server/identity" -body '{"clientId":"fabric-installer", "clientName":"Fabric Installer" ...... }' -accessToken "eyJhbGciO"

New-ClientCredentialsClientBody

Creates a new hashtable object representing a client. Each property is represented as a Key in the hashtable. The client object returned by this function will use the Client Credentials flow.

The New-ClientCredentialsClientBody function takes the following parameters:

  • clientId
    • The unique text identifier for the client.
  • clientName
    • The human readable name for the client.
  • allowedScopes
    • An array of scope strings which the client will be allowed to request.

Example Request:

New-ClientCredentialsClientBody -clientId "sample-credentials-client" -clientName "Sample Client using Client Credentials" -allowedScopes @("dos/metadata.read")

New-ImplicitClientBody

Creates a new hashtable object representing a client. Each property is represented as a Key in the hashtable. The client object returned by this function will use the Implicit flow.

The New-ImplicitClientBody function takes the following parameters:

  • clientId
    • The unique text identifier for the client.
  • clientName
    • The human readable name for the client.
  • allowedScopes
    • An array of scope strings which the client will be allowed to request.
  • allowedCorsOrigins
    • Array of strings representing the allowed addresses for Cross-Origin Resource Sharing.
  • redirectUris
    • Array of strings representing list of uri's that can request a login redirect.
  • postLogoutRedirectUris
    • Array of strings representing list of uri's that are acceptable navigation after logout.

Example Request:

New-ImplicitClientBody -clientId "sample-implicit-client" -clientName "Sample Client using Implicit Registration" -allowedScopes @("dos/metadata.read") -allowedCorsOrigins @('http://some.server', 'https://some.other.server') -redirectUris @('https://some.server/loginRedirect') -postLogoutRedirectUris @('https://some.other.server/logoutRedirect')

New-HybridClientBody

Creates a new hashtable object representing a client. Each property is represented as a Key in the hashtable. The client object returned by this function will use the Hybrid flow.

The New-HybridClientBody function takes the following parameters:

  • clientId
    • The unique text identifier for the client.
  • clientName
    • The human readable name for the client.
  • allowedScopes
    • An array of scope strings which the client will be allowed to request.
  • allowedCorsOrigins
    • Array of strings representing the allowed addresses for Cross-Origin Resource Sharing.
  • redirectUris
    • Array of strings representing list of uri's that can request a login redirect.
  • postLogoutRedirectUris
    • Array of strings representing list of uri's that are acceptable navigation after logout.

Example Request:

New-HybridClientBody -clientId "sample-hybrid-client" -clientName "Sample Client using Hybrid Registration" -allowedScopes @("dos/metadata.read") -allowedCorsOrigins @('http://some.server', 'https://some.other.server') -redirectUris @('https://some.server/loginRedirect') -postLogoutRedirectUris @('https://some.other.server/logoutRedirect')

New-HybridPkceClientBody

Creates a new hashtable object representing a client. Each property is represented as a Key in the hashtable. The client object returned by this function will use the Hybrid flow with PKCE.

The New-HybridPkceClientBody function takes the following parameters:

  • clientId
    • The unique text identifier for the client.
  • clientName
    • The human readable name for the client.
  • allowedScopes
    • An array of scope strings which the client will be allowed to request.
  • redirectUris
    • Array of strings representing list of uri's that can request a login redirect.

Example Request:

New-HybridPkceClientBody -clientId "sample-hybridpkce-client" -clientName "Sample Client using Hybrid and PKCE Registration" -allowedScopes @("dos/metadata.read") -redirectUris @('https://some.server/loginRedirect')

Edit-ClientRegistration

Attempts to update the registration of an existing identity client If successful, returns a new client secret for the client.

Exceptions thrown in this function are wrapped, and may be access through the InnerException.

Edit-ClientRegistration takes the following parameters:

  • identityUrl
    • The base identity url
  • body
  • accessToken
    • An access token previously retrieved from the identity server

Example Request:

Edit-ClientRegistration -identityUrl "https://server/identity" -body '{"clientId":"fabric-installer", "clientName":"Fabric Installer" ...... }' -accessToken "eyJhbGciO"

Reset-ClientPassword

Attempts to reset the client secret an existing identity client If successful, returns a new client secret for the client.

Exceptions thrown in this function are wrapped, and may be access through the InnerException.

Reset-ClientPassword takes the following parameters:

  • identityUrl
    • The base identity url
  • clientId
    • The unique identifier of the client to reset
  • accessToken
    • An access token previously retrieved from the identity server

Example Request:

Reset-ClientPassword -identityUrl "https://server/identity" -clientId "someClient" -accessToken "eyJhbGciO"

Test-IsClientRegistered

Checks for the existence of a specific identity client. If the client exists, returns true, else false.

Test-IsClientRegistered takes the following parameters:

  • identityUrl
    • The base identity url
  • clientId
    • The unique identifier of the client to find
  • accessToken
    • An access token previously retrieved from the identity server

Example Request:

Test-IsClientRegistered -identityUrl "https://server/identity" -clientId "someClient" -accessToken "eyJhbGciO"

Get-ApiRegistration

Attempts to retrieve information about an existing identity api. Returns an Api object. The object matches the properties from Fabric.Identity.API.Models.ApiResource

Get-ApiRegistration takes the following parameters:

  • identityUrl
    • The base identity url
  • apiName
    • The unique name of the api to find
  • accessToken
    • An access token previously retrieved from the identity server

Example Request:

Get-ApiRegistration -identityUrl "https://server/identity" -apiName "sample-api" -accessToken "eyJhbGciO"

New-ApiRegistration

Attempts to register a new identity api. If successful, it returns an api secret for the new api. If the api already exists, this function updates the api attributes and resets the api secret. Exceptions thrown in this function are wrapped, and may be accessed through the InnerException.

New-ApiRegistration takes the following parameters:

  • identityUrl
    • The base identity url
  • body
  • accessToken
    • An access token previously retrieved from the identity server

Example Request:

New-ApiRegistration -identityUrl "https://server/identity" -body "{"enabled":true, "name": "sample-api", "userClaims":["name"], "scopes":[{"name" = "sample-api"}]}" -accessToken "eyJhbGciO"

New-ApiRegistrationBody

Creates a new hashtable object representing an api. Each property is represented as a Key in the hashtable.

New-ApiRegistrationBody takes the following parameters:

  • apiName
    • The name for the api
  • userClaims
    • An array of claim strings that the api can request
  • scopes
  • isEnabled
    • A string true/false value that enables or disables the use of this api

Example Request:

New-ApiRegistrationBody -apiName "this-Api" -userClaims @("name", "email", "role", "groups") -scopes @{"name" = "sample-api"; "displayName" = "Sample-API"} -isEnabled true

Remove-ApiRegistration

Attempts to delete the registration of an existing identity api. If successful, it returns an empty string. Exceptions thrown in this function are wrapped, and may be accessed through the InnerException.

Remove-ApiRegistration takes the following parameters:

  • identityUrl
    • The base identity url
  • apiName
    • The name of the existing api
  • accessToken
    • An access token previously retrieved from the identity server

Example Request:

Remove-ApiRegistration -identityUrl "https://server/identity" -apiName "sample-api" -accessToken "eyJhbGciO"

Edit-ApiRegistration

Attempts to update the registration of an existing identity api. If successful, it returns a new api secret for the api. Exceptions thrown in this function are wrapped, and may be accessed through the InnerException.

Edit-ApiRegistration takes the following parameters:

  • identityUrl
    • The base identity url
  • body
  • apiName
    • The name of the existing api
  • accessToken
    • An access token previously retrieved from the identity server

Example Request:

Edit-ApiRegistration -identityUrl "https://server/identity" -body "{"enabled":true, "name": "sample-api", "userClaims":["name"], "scopes":[{"name" = "sample-api"}]}" -apiName "sample-api" -accessToken "eyJhbGciO"

Reset-ApiPassword

Attempts to reset the api secret of an existing identity api. If successful, it returns a new api secret for the api. Exceptions thrown in this function are wrapped, and may be accessed through the InnerException.

Reset-ApiPassword takes the following parameters:

  • identityUrl
    • The base identity url
  • apiName
    • The name of the existing api
  • accessToken
    • An access token previously retrieved from the identity server

Example Request:

Reset-ApiPassword -identityUrl "https://server/identity" -apiName "sample-api" -accessToken "eyJhbGciO"

Test-IsApiRegistered

Checks for the existence of a specific identity api. If the api exists, returns true, else false.

Test-IsApiRegistered takes the following parameters:

  • identityUrl
    • The base identity url
  • apiName
    • The name of the existing api
  • accessToken
    • An access token previously retrieved from the identity server

Example Request:

Test-IsApiRegistered -identityUrl "https://server/identity" -apiName "sample-api" -accessToken "eyJhbGciO"

Table of Contents

Overview

API Reference

Installation and Configuration

Clone this wiki locally