SAP Customer Data Cloud Positions

Organization Management Detailed User Guide

Skip to end of metadata
Go to start of metadata

Description

Part I. - Activate Organization Management on Site Group Level

  • How to enable Organization Management.

Part II. - Organization Management and profiles

  • How to login and navigate within Organization Management.
  • Recommended Administration Flow in Organization Management.
  • Organization Management profiles.

Part III. - Policy building blocks and creating an access policy

Once your initial Partner and Site Groups are created, you can begin to build your authorization Policy. In order to do so, you must define and build out the following elements:

  • New Roles and/or Dynamic Groups.
  • Asset Templates, which you will use to add new Assets into your Policy. All Assets in your Policy are based on a Template, which enables you to choose specific available Actions.
  • Actions for your Assets. For example, a template might have Actions CREATE, ORDER, READ, SUBMIT, DELETE, and for a specific Policy you may choose to enable only the READ Action.
  • Asset Rules.
  • Applications.

Once these pieces are in place you can build authorization policy that defines who can do what, and when.

Part IV. - Site Group Configuration and Organization Creation

  • Create and manage Site Groups and Organizations in your environment.
  • Define a workflow that will enable you to approve Organizations.
  • Update the Security Profile and Approval Workflow with your new Dynamic Groups (and/or Roles) so that you can create and approve Organizations.

Part V. - Manage Organizations

  • How to invite, manage and assign roles to organization members.
  • Review of Manage organizations API.
  • Detailed API Tutorial

Part VI. - Verify Authorization Request

  • Explains how you can set-up an authorization token for a request made by a specific application in the context of a specific organization.

Part VII. - Appendices

 

 

Unable to render {include} The included page could not be found.

 

I. Activate Organization Management on Site Group Level

In the Admin section of the Console you can see Organization Management in the menu. Click it to see which Sites and Site Groups have Organization Management activated, and click Activate on new Sites and Site Groups to enable them.

Please note that it might take couple of minutes until the site appears in Organization Management.

 

New Sites and Site Groups can be deactivated by clicking on Deactivate. Once clicked, the site and its organizations will not be shown in the Organization Management dashboard (admin logout and login may be required).   

 

II. Organization Management

When you are being redirected from the CDC to the Organization Management module, a menu will allow you to select the level (Partner, Site Group, Organization) you wish to work with.

The Organization Management interface is based upon the user_type passed in the JWT. IT admins can navigate between all levels, while Delegated Admins will see a limited view of the Organization view (only Members).

Each level (Site Group, Organization) is configured on the level above. The levels are shown both on the selection menu and from within the Organization Management console.

 

 

To manage a specific level, click MANAGE on the selected unit. To view the Site Groups or Organizations under them click EXPAND.

You can navigate between levels by clicking the Switch icon in the right upper corner which will navigate you back to the levels selection menu:

 

Organization Management – Profiles

IT Admin

A CDC user who has access to all management levels in the Organization Management Console.

Capabilities:

  • Manage Roles.
  • Manage Access Policies – global access policy for Partners, access policy for Site Groups, and access policy for Organizations.
  • Manage Organization members – Invite, Update, Add/Remove roles, Changes status, Reset password.
  • Organization Management – Set up approval workflow, Approve/Decline organizations.

IT Admins are shown in the Partner level under the Identities->Admin page:

 

Delegated Admin

A Delegated Admin of the customer who can manage members inside an Organization in a limited view of the Organization Management console.

Capabilities:

  • Manage Organization members
    • Invite, Update, Remove members
    • Activate/Deactivate members
    • Add/Remove member roles
    • Change member's status
    • Reset member's password

In Organization Management there is a built in role called Delegated Admin. Each member who has a delegated admin role in the organization can perform the above mentioned actions, and has the role associated to their profile.

 

End User

The member of an organization (Identity) by whom the authorization request and response is performed (based on predefined roles, dynamic groups, and policies).

 

Administration Flows in Organization Management

 

III. Policy Building Blocks and Access Policy End-to-End

Creating an access policy is divided into two main sections:

  1. Preparing to build a Policy (creating the Policy building blocks)
  2. Building an access policy

Note: Once the building blocks are created, you can use them to build as many policies as required.

1. Preparing to Build a Policy: Policy Building Blocks

Before you can start building a Policy, you must create the required building blocks. This section describes how to create all the required Policy building blocks.

The steps to create the building blocks of a Policy are:

 

Note: Policy building blocks can be created at the Partner level or Site Group Level. We recommend that you follow these guidelines:

Create on Partner levelCreate on Site Group level
  • Dynamic Group – for IT Admins
  • Roles - for IT Admins
  • Actions
  • Asset template - only if used across Site Groups within the same Partner
  • Asset Rules - only if used across Site Groups within the same partner
  • Assets - only if used across Site Groups within the same partner

Though Policies and Applications can be created on the Partner level, it is recommended to create them only on Site Group level.

  • Policies
  • Applications
  • Dynamic Group - for organization members
  • Roles - for organization members
  • Asset template - If used only within this Site Group
  • Asset Rules (If used only within this Site Group)
  • Assets (If used only within this Site Group)

 

1. Create/Manage Roles

What is a Role?

A Role represents a business function that can be associated with a user (organization member or IT Admin). For example:

  • Banker
  • Clerk
  • Doctor
  • Nurse
  • etc.
Step DetailsExpected Result
Connect to the Organization Management console as the IT Admin and choose a Site Group or Partner level to connect to.Welcome page

Go to Identities > Roles


Display a list of existing roles

Click CREATE NEW


Displays new static role screen with the following fields:
*Name (required field) - free text

*Status button

*Description-free text

*Member schema (required field):

- For Org member Roles, select Site Group template

- For IT Admin Roles, select Partner template

*Organization Management Settings –

- For Org members Roles choose Hierarchy

- For IT admins, choose Private

Fill in Required fields - Name, Identity template and values 
Click APPLYStatic role is saved and displayed at the top of static roles list

 

2. Create/Manage Dynamic Groups

What is a Dynamic Group?

A Dynamic Group represents a collection of users that is constructed based on their attributes.

Note: User attributes are sourced from their CDC Account.

Step Details

Expected Result

Connect to Organization Management with IT admin and choose a Site Group/Partner level to connect to

 

Show welcome page

Go to Identities > Dynamic Group

1. Display a list of existing Dynamic Groups

 

Click CREATE NEW

 

2. Displays new Dynamic Group screen with the following fields :
*Name (required field) - free text

*Status

*Description-free text

*Identity template

*Rule set – include/exclude

- Select required attributes and values to be included in the rule set.

*Member schema (required field):

- For Org member Roles, select Site Group template

- For IT Admin Roles, select Partner template

*Organization usage settings:

- For Org members Roles choose Hierarchy

- For IT admins, choose Private

 

Fill in Required fields - Name, Identity template and values

Required fields filled

Click APPLY

Static role is saved and displayed at the top of static roles list

 

3. Create/Manage Actions

What is an Action in Organization Management?

An Action is part of the authorization response; it communicates to the application what is permitted on the requested Asset. For example, CREATE, READ, UPDATE, and DELETE, are common actions.

Step Details

Expected Result

Connect to Organization Management with an IT admin and choose a partner level to connect to

Show welcome page

Go to IMPLEMENTATION > ASSETS > ACTIONS

 

Click CREATE NEW

Open a new action

Fill in name, description and action and click SAVE

Action saved


4. Create/Manage Asset Templates

What is an Asset Template?

You need an Asset Template prior to creating an Asset.

An Asset defines the objects (resources) your Application can act upon. Each Asset is based on a specific Asset Template, and uses the available Asset attributes and possible actions defined in the Asset Template to create a unique Asset in your Policy. Assets are described in greater detail in the next section.

An Asset Template includes the full list of asset Attributes and a full list of possible Actions. When you build an Asset Template you must specify all the possible actions and attributes you may want to use in your various assets. You can then choose which of those actions you want to enable for each individual asset you create.

For example: Account Record

List of attributes: Name, Type, Status, Amount

Associated actions: View, Edit

Step Details

Expected Result

Connect to Organization Management with an IT admin and choose a partner/Site Group to connect to

Show welcome page

Go to IMPLEMENTATION > ASSETS> TEMPLATES

It lists all the Templates and the details of the first one in the list

Click CREATE NEW

Opens a new Template with all the fields to fill

Fill:
1.Name
2.Description
3. Repository - virtual repository/Internal
4. Asset Attribute - put a name and choose type
5. Action - click Add Actions and add an Action
6. Click Save

 

Important:

Internal – Enables management of Assets within the system – If you need the authorization response to return a list of assets, choose this option!

Virtual – Support Assets data only via the authorization request.

Virtual asset template saved


5. Create/Manage Asset Rules

What is an Asset Rule?

An Asset Rule is an optional filter on the asset, used in Access policies.

For example: VIP Accounts, Basic Accounts

Step Details

Expected Result

Connect to Organization Management with IT admin and choose a Partner/Site Group to connect to

Show welcome page

Go to implementation > Rules

Template selection is available and also the CREATE NEW button

Click the CREATE NEW button

The list of templates appears in the drop-down

Select the Asset Template you created:

The template is selected and fields can be filled in:
* Name

* Description

* Attribute

* Settings

* Operator

* Value

* Organization management settings

* Organization usage settings

* SAVE

Click SAVE

New asset rule is displayed in list when the template is selected.


6. Create/Manage Assets

What is an Asset?

An Asset defines a resource that your Application can act upon. Each Asset is based on a specific Asset Template, and uses the available Asset attributes and possible actions defined in the Asset Template to create a unique Asset in your Policy.

For example: AccountA is an asset that has been defined by your company and needs specific authorization permissions.

  • Name: AccountA
  • Type: Basic
  • Status: Active
  • Actions: View; Update

Step Details

Expected Result

Connect to Organization Management with IT admin and choose a partner/Site Group to connect to

Show welcome page

Go to implementation >  Manage

Asset selection is available and also the CREATE NEW button

Click the CREATE NEW button

The list of Templates appears in the drop-down

Select the Asset Template you created

Fill in all relevant attributes

 

Click SAVE

New Asset is displayed in list for the selected Asset Template

 

7. Create/Manage Applications

What is an Application?

An Application represents the component that consumes the authorization information delivered by Organization Management.

The Application is associated with a unique identifier that is required to submit valid authorization requests. Organization Management uses this unique identifier to provide the correct authorization for the Application.

Step Details

Expected Result

Connect to Organization Management with IT admin and choose a Site Group to connect to

show welcome page

Go to implementation > APPLICATIONS

Lists the Applications and the details of the first one in the list

Click CREATE NEW

Opens a new application

Enter Name and Description and save

application saved and appears in the list

Go to the Adaptive Asset tab of the Application you created

This tab presents a list of Assets that can be accessed by the Application, no need to change the list!

Click the Keys icon

A pop-up lists the Application client keys

Enter a value for Token validity (0 is default)

Client ID and Client Secret appear (keep the Client ID for later)

Click save

Exit the pop-up

 

8. Create Conditions (optional)

Conditions place limits on the identities (dynamic groups and roles) in the policy map.

There are 2 types:

  1. Time restrictions (defined in GMT)



  2. Advanced
  • E.g., IP address, authentication method, additional identity attribute



2. Building a Policy

 Step Details

Expected Result

Log into Organization Management as an IT Admin and connect to a Site Group

Welcome page appears

Click Policies

The list of Policies appears, with the first Policy in the list in the main UI

 

Click CREATE NEW

The New Policy dialog box appears

  1. Fill in the Policy Name and Description
  2. Policy type: Access
  3. Click the checkbox to enable Use Walkthrough assistance to create policy
  4. Click SAVE

The walkthrough assistant guides you through the steps to create a policy – Who, When and What.

Click the link button to Connect Dynamic Groups and Members

-          Select Roles or Dynamic Group (whichever you have prepared to be used in the policies)

 

Note: This example will focus on Roles.

Click Search to view a list of existing Roles, and select any you wish to connect to the Policy.

 

 

Click APPLY

The Policy with selected Roles appears, and the Assistant guides you to the next step, connecting Conditions.  

Click the Conditions icon to add conditions, or SKIP to the next step.

Connect Assets - click the Link icon to select the Asset Template you want to use in the Policy.

From the list, select the Asset Template you wish to use.

Once you select the Asset Template, a six step dialog box appears:

  1. Select Actions.

Click to select the Actions you want to enable for this Policy.

 

Click CONTINUE

  1. 2. Assets – Select specific Assets to be part of the Policy or SKIP this step.

 

Note: Typically you would SKIP this step.

  1. 3. Assets Rules

Click Manage Asset Rules to select the relevant Rules for this Policy.

Manage Asset Rules – Enables selection of the logical expressions associated with the Rule that should be part of this Policy.

 

Build the policy logic and click SAVE.

And then click CONTINUE.

 

  1. Constraints – SKIP this step
  2. Obligations – SKIP this step.

 

Note: Constraints and Obligations are advanced policy settings that typically will not be used.

  1. 6. Application

Select the relevant Application for this Policy from the list.

 

Click SAVE.

The policy creation process is completed.

Click DONE.

Important!

Click Deploy to deploy your policy.

 

 


IV. Site Group Configuration and Organization Creation

 

The organization management settings of a specific site/sitegorup can be defined on the Partner level: define approval workflow for organizations, assign role to security profiles (organization approver, policy approver, Administrators for various objects (policy, application, resource, user), organization approval or invite emails, change the display settings (name, icon)..  This step is recommended before starting to create organizations.

1. Define Organization Approval Workflow (Optional)

The Approval Workflow is set up on the Partner level for each Site Group separately to define the approval path when you create a new Organization. It shows identities and the position that should approve the new Organization. You can set up multiple roles, and multiple paths with dependencies on each other.

If no workflow is set up the new organizations will be approved automatically.

This section describes the steps required to customize the workflow so that you can approve the organizations you are creating. 

Step Details

Expected Result

Login with IT admin on the Partner level

(on partner namespace selection popup click Manage)

Welcome page in partner view appears

Click Settings

 

Select the Site Group in which the Organization is located

Go to the Approval tab and select Organization to set up the workflow

Add role or roles (you can add multiple roles)

Roles appear in the approval path (you can add more)

Give a name or names for all paths you defined.

Click Save

If you do not give a name you will get the following error:

If no role is defined for the path you will get the following error message:

If the approval flow is successfully saved, you will get no error message and the changes will be saved:

 


In case you wish to add single identities or group of identities defined in a new role (other than the predefined ones), please follow the steps described in APPENDIX - Workflow Creation – Configure Approver Role

 

2. Create Organizations

Organizations can be created within the UI on Site Group level only. Organization self-registration can be provided to customers.

Organizations need to be approved before members can be invited. The identities defined in the approval workflow are responsible to approve/decline new organization requests.

Create a New Organization Within the UI

Step Details

Expected Result

Connect with IT admin to a Site Group level (Select a Site Group on the namespace selection popup after being redirected from the SAP Console)

Show welcome page

Click Organizations then click Management and click CREATE NEW

New organization creation pop up – Step 1

Fill in the required fields, select the customer type and click SAVE & CONTINUE.

New organization creation pop up – Step 2

In this step you can define the template email that you wish to send for invited members.

You can take the template from the site as per default, in this case no action is required here.

Or you can define a specific invite template for the organization. This can be edited later at any time.

Click SAVE

Click SAVE

Pop up closes, and new Organization is created and displayed in the Organization list.

Organization created

You can either send it for approval right away or save it as a draft and edit later.

Update Organization details

You can update all the Organization details specified in Organization creation earlier by clicking the Edit button: Details, Invite tabs

Update Organization details

You can update the Organization logo shown in the UI here.

 

Registration Requests

The organization contact person can also submit an Organization registration request online (e.g., Partner Portal). Alternatively, a new organization registration request may be provisioned through the API from another application (e.g., sales automation system), in this case the Organization registration request will appear in the UI by Registration requests and the user will have the following options:

  • Create New Organization (pop up will appear and only then the request will be sent for approval)
  • Reject the registration request
  • If the name is similar to an existing Organization name the invite icon will be available - and the requestor can be invited to an existing Organization
  • Edit the Organization details in the request (status will not change)

 

Send New Organization for Approval

Step Details

Expected Result

You can send an organization for approval in two ways:

  1. Immediately after you create by clicking the pop up on SEND FOR APPROVAL
  2. In the draft Organization click the icon to send the Organization for approval.

 

Please note a comment is required when sending the new Organization for approval.

 

Once comments have been added please click the SUBMIT button and you will get a notification on the top of the page that the new Organization Request has been sent for approval.

 

The approver will get an email notification about the creation of the new organization and that it is waiting for his approval.*

If a workflow is set as mandatory for approving new organizations, and the workflow steps haven’t been defined yet, you will get an error message.

 

If a workflow is not set as mandatory, new organizations will be approved automatically.

If there is no workflow the following error message appears:

 

Approve/Decline Organizations

The Organization Management view shows the organizations in 3 main statuses:

  1. Defined – approved, suspended
  2. Pending – in-progress, registration request
  3. Others – draft, declined

 

Organizations in status PENDING are awaiting the approval of the Organization Approver. Only after the Approver has approved the Organization can new members be invited to join.

 

Import Organizations using API

You can import multiple organizations by using the following POST API call:

API 

Description

Request URL

POST 

https://api.b2b-gigya.com/gigya/organizations/{tenantid}/{sitegroup-id}/import

A Bearer token is required to be added to the request.

Request Parameters

URL Params:

update = false/true
status = draft/approved/suspended 

userUid = UID in gigya of the user doing the action

Body Params:

Array of JSONs, for example:
[
{"name":"batch5",
"description":"autoGenerated",
"membersLimit":123,
"externalId":5,
"type":"CUSTOMER",
"fields":{"city":["a"]},
"metadata":{"useParentDisplay":true}}
]
identification is by externalid
name and externalid should be unique

Response

"import successful" or an error

Status Codes

200 - success

404 - something missing (site group, org template, org admin role etc.)

400 - something is wrong (too many orgs, orgs exist and update is false, twice the same org in the request etc.)

 

V. Manage an organization

You can manage an organization by defining the administrators or the Delegated Admin role (previously called OrgAdmin role, please note that in older instances this role is still displayed with this OrgAdmin name) and adding/inviting members to it. You can add predefined roles to the members, e.g.: reseller, buyer, VIP buyer, etc.

1. Invite Members, Delegated Admins

Step Details

Expected Result

Log into Organization Management with IT Admin credentials and select an Organization (select the Organization on the namespace selection pop up)

n/a

Click Members in the menu and click the INVITE button

Fill in all the required information to invite a member

Invite a member window appears

Here you can add predefined roles to the person

Add a Business Role if you wish to grant admin rights to the person in the given organization.

Member invite via email

Member is invited successfully and will receive the invite from noreply@gigya.com with the first-time password.

The new member will be displayed in the members list, and will be saved in Gigya’s console as well.


You can also enable previously invited members to add Delegated Admins by assigning them the relevant Business Role.

2. Reset Member Password

Both IT Admin and Delegated Admin have the rights to reset passwords for organization members.

On the organization level please go to members and select the member you want to reset password for and click Reset password icon in the right upper corner of the identity details:

 

3. Add Role to Members

Both IT Admin and Delegated Admin have the rights to add/remove roles of a member.

On the organization level please go to Members and select the member where you would like to make changes. Go to the Role Management tab and you can add or remove roles.

 

4. Manage Organizations API

The following APIs can provide reports about organizations per sites or by BPID.

You can use any REST client tool, such as Postman, Paw or SoapUI, to send a request example and test the response. Various API request parameters can be found in the APPENDIX – Request building parameters.

Get Roles List By Site

API 

Description

Request URL

GET 

https://api.b2b-gigya.com/gigya/organizations/{tenantid}/roles/sitegroup/{sitegroup-id}

A Bearer token is required to be added to the request.

Request Parameters

8910472

Response

[{
"roleId": "8ffc5f27-bdb1-4cbb-8a20-65dc999cdbaa",
"roleName": "Test Role",
"ruleSet": "e09e84fa-d4e5-41ff-8ad3-92c984467519"
}]

Status Codes

200 OK

 

Get List Of Organizations By Site

Th API shows approved/suspended organizations only (which have a namespace created in Organization Management)

APIDescription
Request URL

/GET 

https://api.b2b-gigya.com/gigya/organizations/{tenantid}/org/sitegroup/{sitegroup-id}

A Bearer token is required to be added to the request.

Request Parameters
9178672
Response
[
	{
		"orgName": "eden2804 9178672_Org 1",
		"bpid": "",
		"orgId": "3e51a7a2-a25b-47a1-8d9c-7a522a05abf1"
	},
	{
		"orgName": "eden2804 9178672_stav_org",
		"bpid": "",
		"orgId": "72df6c67-4b7e-4cad-9761-ff4fda766c26" 
	}
]
Status Codes200 OK

 

Get Organization by BPID

API 

Description

Request URL

/GET 

https://api.b2b-gigya.com/gigya/organizations/{tenantid}/?bpid=BPID

A Bearer token is required to be added to the request.

Request Parameters

String; Business partner ID. This is the FK of the organization in the origin system. It needs to be unique and lookupable

Response
{
	"name": "liraz 0805 2",
	"status": "IN_PROGRESS",
	"bpid": "t",
	"id": "c20bbaf1-07d6-4017-aeb1-a7af01a03bcd"
 }

Status Codes

500,404, 400, 200

 

Detailed API Tutorial

Construct the API URI

To send the request, construct the API URI as follows, where <YOUR-GIGYA-API-KEY> is the Gigya API key associated with this site or site group in the Gigya Console and <YOUR-ORG-MNGT-APP-CLIENT-ID> is the Client ID you obtained from the Organization Management dashboard in the previous section.

Basic Authorization API Format
https://us1api.b2b-gigya.com/runtime/<YOUR-GIGYA-API-KEY>/authorization/basic/<YOUR-ORG-MNGT-APP-CLIENT-ID>

This example URI is used for Basic authorization, for constructing a Detailed authorization request see LINK:TBD .

 

Insert the URI you constructed above, into the Postman interface as a POST request.

 

Configure The POST Body

Next, we will configure our POST body, using the raw option so we can paste our JSON directly.

The generic format of a request is detailed below.

Basic Authorization JSON Structure
// Note: JSON must not contain comments
{
    "identity": {
        "id": "<THE-GIGYA-UID-OF-THE-USER-TO-VALIDATE>"
    },  
    "context": {
        "organization": "<THE-ORG-MNGT-orgId-OF-THE-USER'S-ORGANIZATION>"
    },
    
    "assets": [
        {
            "type": "urls",  // Asset template name
            "path": "admin", // path of resource or "/"
            "actions": ["view_url"], // Attempted action(s)
            "attributes": {
                "url": ["public"] // name of the asset being accessed
            }
        }
    ]
}

 

 

After providing the applicable data for your user, enter it into Postman, ensuring that you have JSON (application/json) selected from the drop-down options.

 

 

Configure the POST Authorization Token

To construct our authorization JWT we will use https://jwt.io

Navigate to jwt.io and make the following changes:

The HEADER should be the default of:

  • "alg" : "HS256"
  • "typ" : "JWT"

The PAYLOAD DATA should be edited to contain only the following properties:

  • iss - Where this is the Authorization Request API key (CDC API key) from above, which is associated to the client_id in the request.
  • exp - Is the time the token will expire in Unix format, i.e., 1558868994; this must be no more than five (5) minutes (300 seconds) from the time the token is sent. For testing, you can use the Expiration Generator tool below.

In the VERIFY SIGNATURE section you should check the Secret Base64 encoded option and input your secret (from the Authorization Request API key section) into the available field.

 

Copy the JWT from the left-hand pane and paste it into the Token field of the Authorization tab of Postman, being sure to select Bearer Token from the left drop-down.

 

 

Sending The Request

If you have previously constructed the POST body, you can now send the test request to the Organization Management server for a response. If you have constructed the request properly, you will receive one of the following two responses:

  • allow

    Authorized Response
    {
        "access": "allow"
    }
  • deny

    Denied Response
    {
        "access": "deny"
    }

Expiration Generator

Generate an EXP for your JWT

This tool will generate an EXP based upon the current time and add the inputted value to it.

Enter TTL of token (in seconds):      

0000000000

 

The maximum allowed lifetime of a supported JWT is 300 seconds. Using any value larger than this will result in the following error response from the authorization server:

{
    "exp": "expired"
}

 

VI. Authorization Request

 

Type

Question

Answer

Request

Can an identity in a specific context access the given assets on the given application?

  1. Basic: Permit/Deny
  2. Detailed: Asset list with permit/deny

Token

Which assets can the identity access in a specific context in the given application?

Full Access list


Below you can find samples for both request types and then the detailed instructions how to get the relevant data required to build the authorization request to test policies.

 

1. Authorization request (Basic/Detailed)

This request type is recommended to use when you would like to do a specific authorization check if the person as or has not access to a specific asset.

 

API 

Description

Request URL

POST  

///{env-url}/runtime/{repo-api-key}/authorization/{basic/detailed}/{application-client-id}

Sample:

https://us1api.b2b-gigya.com/runtime/3_gGKTccV0-VAWhY52CQ5Fs4J1y6RDApnqEr0WkwDnXDRFb_aL-ztmOOU3puHUeIci/authorization/basic/EOZ6LUIW6J5QFAOVUFAA

Request Parameters

authorization-request

{
	"identity": {
		"type": "user",
		"id": "user1", 
        "attributes": {
            "attribute1": ["aaa","cc"],
            "attribute2": ["bbb"]
        }
    },
    "context": {
        "originating_ip": "10.10.10.1",
        "environment": {
			"attribute1": ["aaa","cc"],
			"attribute2": ["bbb"]
		},
		"organization": "orgid" 
	},
	"assets": [
		{
            "type": "virtual-asset1",
            "path": "path",
            "actions": [
				"read",
				"write"
			],
            "attributes": {
                "attribute1": [
					"ccc"
				],
                "attribute2": [
					"ddd"
				]
            }
        },
        {
            "type": "virtual-asset2",
            "path": "path",
            "actions": ["read"],
            "attributes": {
				"attribute1": [
					"eee",
					"ee"
				],
				attribute2": [
					"fff"
				]
			}
		}
	],
	"response": {
		"include_identity": true,
		"include_reasons": true
	}
}

Response (basic)

authorization-response

HTTP 1.1 Status: 200 OK
 
{
    "access": "allow|deny",
    "identity": {
		"type": "maya.com",
		"attributes": {
			"firstName": ["amitai3"]
		}
	},
	"reasons": {
		"access_policies": [
			{
				"id": "17:16",
				"active": true,
				"restricted": false
			}
		],
		"context": {
		}
    }
}

Response (detail)

authorization-response

HTTP 1.1 Status: 200 OK
{
         "approved_assets": [{
                                   "type": "asset1",
                                   "action": "read",
                                   "attributes": {
                                            "attribute1": ["ccc"],
                                            "attribute2": ["ddd"]
                                   }]
                          },
                          {
                                   "type": "asset2",
                                   "actions": ["read"],
                                   "attributes": [{
                                            "attribute1": ["eee"],
                                            "attribute2": ["fff"]
                                   }]
                          }
                 ],
         "rejected_access": {
                 "assets": [{
                          "type": "asset3",
                          "actions": ["write"],
                          "attributes": {
                                   "attribute1": ["ggg"],
                                   "attribute2": ["hhh"]
                          }]
                 }]
         },
         "identity": {
        "type": "maya.com",
        "attributes": {
            "firstName": ["amitai3"]
                 }
    },
         "reasons": {
        "access_policies": [
            {
                "id": "17:16",
                "active": true,
                "restricted": false
            }
        ],
        "context": {
        }
    }
}

Status Codes

200 - OK - (to both allow or deny)

400 - Bad Request - (invalid input parameters)

401 - Unauthorized - (no credentials were given)

403 - Forbidden - (failed to validate credentials)

413 - Payload Too Large - (too big input parameters payload, use POST instead of GET)

500 - Internal Server Error - (unexpected server error)

2. Authorization token

This request type is recommended to use when you would like to get a full access request of a specific identity.

API 

Description

Request URL

POST

//{env-url}/runtime/{repo-api-key}/authorization/token/{application-client-id}

Sample:

https://us1api.b2b-gigya.com/runtime/3_gGKTccV0-VAWhY52CQ5Fs4J1y6RDApnqEr0WkwDnXDRFb_aL-ztmOOU3puHUeIci/authorization/token/ EOZ6LUIW6J5QFAOVUFAA

Request Parameters

authorization-request (mandatory attributes marked in green)

{
         "identity": {
                 "type": "user",
                 "id": "user1",
                 "attributes": {
                          "attribute1": ["aaa"],
                          "attribute2": ["bbb"]
                 }]
         },
         "context": {
                 "originating_ip": "10.10.10.1",
                 "environment": {
                          "attribute1": ["aaa","cc"],
                          "attribute2": ["bbb"]
                 },
                 "organization": "orgid"
         },
         "assets": [{
                          "type": "virtual-asset1",
            "path": "path",
                          "actions": ["read", "write"],
                          "attributes": {
                                   "attribute1": ["ccc"],
                                   "attribute2": ["ddd"]
                          }
                 },
                 {
                          "type": "virtual-asset2",
            "path": "path",
                          "actions": ["read"],
                          "attributes": {
                                   "attribute1": ["eee","ee"],
                                   "attribute2": ["fff"]
                          }
                 }
         ],
         "response": {
        "include_identity": true,
        "include_reasons": true
         }
}

Response 

authorization-response 
HTTP 1.1 Status: 200 OK
 
{
    "assets": {
        "templates": {
            "test1": {
                "actions": {
                    "action1": [
                        {
                            "path": "asdasd11",
                            "attributes": {
                                "number": ["1"],
                                "first_name": ["ba"]
                            }
                                                             "conditions": {
                                                                      "constraints": [],
                                                                      "obligations": []
                                                             }
                        },
                        {
                            "path": "aaaa",
                            "attributes": {
                                "first_name": ["bb"]
                            }
                        }
                    ]
                }
            }
        }
}

Status Codes

200 - OK - (to both allow or deny)

400 - Bad Request - (invalid input parameters)

401 - Unauthorized - (no credentials were given)

403 - Forbidden - (failed to validate credentials)

413 - Payload Too Large - (too big input parameters payload, use POST instead of GET)

500 - Internal Server Error - (unexpected server error)

 

3. How do I build the Authorization request?

You can use any REST client tool, such as Postman, Paw or SoapUI, to send a request example and test the response.

Various API request parameters can be found in the APPENDIX – Request building parameters.

  1. Open Postman and create a new request and add the Request URL for the given request type (detailed, basic or token as described earlier)

 

Add the Bearer token:

 

Define your request by adding the relevant parameters:

UID – to define the identity on whom you would like to make the access request

OrgID – Organization should be defined as context data

Assets – assets are required to be defined in the access request only by detailed or basic authorization requests which will give a permit/deny response for the access request question

 

 

Click on the Send button to get a response.

 

VII. Appendices

Demo your app

Once you have set up everything you can attach it to your application and demo it to the customer.

If you require any assistance or have questions, please add it in the following Slack Channel: #cdc-org-mng (If you don’t have access to it, please contact Aliza Zeldin to request access)

 

Workflow Creation – Configure Approver Role

When customizing the Organization approval workflow, you can define identities based on predefined roles as Organization Approver. In case you wish to add single identities or group of identities defined in a new role, please follow the below steps so that you can use them in the Organization Approval workflow setup.

a.     Create Dynamic Groups for specific roles

What is a Dynamic Group?

Dynamic Group represents a collection of users based on their attributes.

Note: users’ attributes originate from CDC repositories.

 

You must create a Dynamic Group to define users that are responsible for reviewing or approving a workflow to approve/decline new Organizations. These roles can be added to the Organization Approver security group and to the Approval path – it is not possible to define single identities as approvers; you must add a role (as a workaround you can add single identities to the specific role you create)

Step Details

Expected Result

Login with IT admin on the Partner level

(on the namespace selection popup select the first options by clicking Manage)

Click Identities > Dynamic Groups

Click CREATE NEW

The following popup appears:

Fill in the required fields to create a new Dynamic Group: Name, Identity template and values

E.g. all identities with Managers as the attribute value for their roles should belong to the group of Org-approver

You can define here single identities to be part of the approver group by adding their email addresses as possible values to the attribute email.

Click SAVE

Role is saved and appears in the list of roles. From now on this role can be added to access policies, members, security profiles or to the approval paths.

 

b.     Organization Approver Security Profile

Organization Approver security profile refers to identities who can approve or decline the creation of new Organizations. Pre-defined roles should be added to this security profile, which will then available when the approval path for Organization creation is defined.

Step Details

Expected Result

Login with IT admin on the Partner level

(on the namespace selection popup select the first options by clicking Manage)

Welcome page in Partner view appears

Click Settings

 

Select the Site Group in which the organization is located

Click Security > Profiles

Lists all predefined Security Profiles.

Select the Organization Approver profile and verify that your required role appears on the right. If not please add the roles that include the specific identities that should be organization approvers.

 

Click CONNECT ROLES and add the specific Dynamic Role to the organization approver profile.

Search for the role you would like to add, select it and click APPLY.

The popup closes, and the role is added to the organization profile.

 

 

Request building parameters

Please find below the bearer token and the attributes required for API calls and explanation how to get their value

a.      Bearer Token

Please note that for all APIs, a bearer token is required, which needs to be sent as a JWT. To create the JWT please navigate to the following website: https://jwt.io/ and insert the following parameters on the right side:

 

  1. iss
  2. Secret

Log in as an IT Admin on the Partner level and go to settings and choose the relevant sitegroup.  ISS and Secret can be found by the settings on the Security / Key Management tab, see below

  1. Exp

The JWT is valid only for a maximum of 5 minutes, please create a new EXP manually by going to the following site: https://www.epochconverter.com/ or using the Expiration Generator below, and define the 5 minutes or less expiration by adding one our more seconds than the current time and take the timestamp which is automatically generated:

 

  1. nbf (Part of the request, but not enforced by Organization Management yet, value does not matter)
  2. iat (Part of the request, but not enforced by Organization Management yet, value does not matter)

 

Token example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIa1N6R1lBcDRMUVI5NWJNUVU3TEdBVXBKcWc3aG1nVyIsImV4cCI6MTQ0MjQzMDA1NCwibmJmIjoxNDQyNDI2NDU0LCJpYXQiOjE0NDI0MjY0NTR9.z-2PLajWhigOJ2_7rPGBr54LMIHTEPo6ef72vJi2suA

 

b.      Repository API Key

Log in as an IT Admin on the Partner level and go to settings and choose the relevant sitegroup.  Repo API key can be found by the settings on the Security / Key Management tab, see below:

 

c.       Application-Client ID

The application client ID is need to connect the request to specific application.

Your Client-id can be found by going to Implementation > Applications > Adaptive Assets and then clicking the Keychain icon:

 

d.      User ID

User ID of the specific identity for which the request is sent can be found easily in the browser console (when clicking on the identity in the members)

 

Or can be found also on the identity access tab in CDC:

e.      Organization ID

OrgID of the specific organization for which the request is sent can be found easily in the browser console (when clicking on the identity in the members)

 

Or can be found also on the identity access tab by Custom Information in CDC:

f.   TenantID, Partner ID, sitegroup ID

Tenant ID can be found in CDC:

Tenant ID is also shown in the URL of Organization Management:

https://example.b2b-gigya.com/app/namespace-selection

g.   Asset - attribues

"assets": [{

            "type": "virtual-asset1",

            "path": "path",

            "actions": ["read", "write"],

            "attributes": {

                "attribute1": ["ccc"],

                "attribute2": ["ddd"]

            }

        },

 

h.      env-url for (runtime)

Limitations

Please bear in mind the below items as current limitations and known issues.

  1. Name of tenant/partner/sitegroup - the IDs are part of the URLs so according to the hostname standard https://tools.ietf.org/html/rfc952 only alpha numeric characters and ‘-‘ (not as suffix or postfix) are supported.
  2. 40 IT admins/partner - if the 41st IT admin logs in, it is not possible to approve workflow.
  3. Browser - Organization Management is supported only in Chrome.
  4. Device type - Organization Management is supported only in Desktop.

 

 

 

 

 

  • No labels