Skip to content

Commit

Permalink
docs(user): fixed typos and updated naming order (#437)
Browse files Browse the repository at this point in the history
  • Loading branch information
MarcMaron authored Nov 28, 2024
1 parent 53a10cd commit d1d321a
Show file tree
Hide file tree
Showing 11 changed files with 40 additions and 40 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ The details below show the user interface as well as the available endpoints to

In the technical integration / setup of the connector, 3 different scenarios are available:

- connector as a service (request a service via a service provider)\
- bring your own connector\
- connector as a service (request a service via a service provider)
- bring your own connector
- no connector required

Connector stakeholders are mainly app providers and data provider (active CX participants along the automotive value chain).
Expand Down
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
# Summary

The IdP Switch function is used to integrate / connect company idp's or switch back to catena-x shared idp usage.
The IdP Switch function is used to integrate/connect company IdP's or switch back to Catena-X shared IdP usage.
<br>

The integration of company idp's is suspected to be the most used scenario when considering the use of idp switch. Companies which want to use their own company authentication can connect their company idp with the catena-x shared idp by using user federation.
The integration of company IdP's is suspected to be the most used scenario when considering the use of IdP switch. Companies which want to use their own company authentication can connect their company IdP with the Catena-X shared IdP by using user federation.
<br>

In this scenario - authentication is delivered by the company idp and authorization is still managed inside Keycloak.
In this scenario - authentication is delivered by the company IdP and authorization is still managed inside Keycloak.
<br>

The biggest positive element on ownCompany idp usage is the comfort of the login, as well as the user credentials which are not shared with an operator.
The biggest positive element on ownCompany IdP usage is the comfort of the login, as well as the user credentials which are not shared with an operator.
<br>

## NOTICE
Expand Down
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
# User Description

How to connect the own idp:
How to connect the own IdP:
<br>

- Request a idp connection
- Upload your company-idp metadata file (please note, CX will mainly support OIDC)
- Request a IdP connection
- Upload your company-IdP metadata file (please note, CX will mainly support OIDC)
- Manually add client-id and secret
- Confirm the IdP config, we will share the authentication URL with you

<br>

After successful setup, the user migration/invite need to take place, before the previous used idp is getting deactivated and deleted.
After successful setup, the user migration/invite needs to take place, before the previous used IdP is being deactivated and deleted.

<br>

Expand All @@ -28,8 +28,8 @@ Details regarding the IAM architecture (applies for shared as well as own IdP us

### Register your company IdP

To register your company idp, login with administration rights and open the "Identity Provider Config" via the top right user navigation.
Inside the config, you will find your current registered (enabled and disabled) identity providers - quite often this will only be one identity provider. As well as the option to register a new identity provider (such as you company idp).
To register your company IdP, login with administration rights and open the "Identity Provider Config" via the top right user navigation.
Inside the config, you will find your current registered (enabled and disabled) identity providers - quite often this will only be one identity provider. As well as the option to register a new identity provider (such as you company IdP).

<br>
<br>
Expand All @@ -41,19 +41,19 @@ Inside the config, you will find your current registered (enabled and disabled)
<br>
<br>

Please note - for the company identity provider connection you will need to prepare certain information to be able to connect your company IdP. Please ensure that all necessary information are available.
Please note - for the company identity provider connection you will need to prepare certain information to be able to connect your company IdP. Please ensure that all necessary information is available.

Currently only the connection for OIDC idp's is supported.
Currently only the connection for OIDC IdP's is supported.

<br>
<br>

#### Create the new idp record
#### Create the new IdP record

Click on "Add Identity Provider" to start the registration.
Inside the overlay the

- idp display name - used for the login company card (users which try to login to CX will see this display name. Use a name which users can understand and know that this belongs to their company)
- IdP display name - used for the login company card (users who try to login to CX will see this display name. Use a name which users can understand and know that this belongs to their company)
- identity provider type - "managed" for onboarding service provider/3rd party acting company and "own" for company owned IdPs
<br>

Expand All @@ -65,7 +65,7 @@ Inside the overlay the

By clicking on "Confirm".

On the upcoming screen the idp relevant connection information need to get added.
On the upcoming screen the IdP relevant connection information needs to get added.
Those are

- metadata url (available in your local/company IdP - ending with /.well-known/openid-configuration)
Expand All @@ -79,7 +79,7 @@ Those are

<br>

if the config was successful, you will get asked to add your personal company idp unique identifier. In this step you will connect your existing catena-x user account (with your already assigned roles and customized configurations) with your company IdP. To do this successfully, you need to add your company IdP unique ID.
If the config was successful, you will be asked to add your personal company IdP unique identifier. In this step you will connect your existing Catena-X user account (with your already assigned roles and customized configurations) with your company IdP. To do this successfully, you need to add your company IdP unique ID.
<br>

<p align="center">
Expand All @@ -88,7 +88,7 @@ if the config was successful, you will get asked to add your personal company id

<br>

With the confirm/submit button the value will get stored successfully and you can now test the company IdP integration by doing a logout and trying to login with your company credentials and company IdP.
With the confirm/submit button the value will get stored successfully and you can now test the company IdP integration by logging out and trying to login with your company credentials and company IdP.
Please note: in this moment, your user is connected with the Catena-X Shared IdP as well as your company IdP. This means, if after the logout and new login via your company IdP you might find out, that the login via the company IdP might not work (due to wrong configuration) you still can login to catena-X with the previous used IdP and correct the IdP config.
<br>

Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#### Migrate existing user accounts to the new created IdP

With the configuration of a new IdP, existing user accounts should not get lost. In the previous section "Create the new idp record" it was already described, how the admin user can connect his/her existing user account with the new company idp. In this section the user migration of additional available user accounts is handled.
With the configuration of a new IdP, existing user accounts should not get lost. In the previous section "Create the new IdP record" it was already described, how the admin user can connect his/her existing user account with the new company IdP. In this section the user migration of additional available user accounts will be explained.
<br>

For the migration of additional existing user accounts, which have been created under the shared IdP previously, the administrator can call the user migration list via the IdP config page.
Expand All @@ -24,7 +24,7 @@ By clicking on the "Users" sub-navigation icon, a overlay with the user migratio
Download the list and add for each user, which is supposed to get migrated to the new IdP.
When opening the csv, add the users identity provider user id in the respective available section - see screenshot below - and upload the csv file as soon as all respective data are added.

Example below shows how to fill the csv file which got downloaded by the IT Admin. In the example 2 users are existing and supposed to get connected to the idp88.
Example below shows how to fill the csv file which got downloaded by the IT Admin. In the example 2 users are existing and supposed to get connected to the IdP88.
Therefor the admin adds for each user the providerUserId and providerUsername. Note: for unique identification the providerUserId is relevant, the userName is only used for reference.

<p align="center">
Expand All @@ -45,8 +45,8 @@ In case any error occurs, details of the upload errors will get displayed per us

<br>

With that, the user migration is successfully done - you can validate the user list again by re-opening the users list of the IdP.
After the successful config, the new IdP can get enabled and the old IdP can get disabled and deleted if required.
With that, the user migration is successful - you can validate the user list again by re-opening the users list of the IdP.
After the successful config, the new IdP can be enabled and the old IdP can be disabled and deleted if required.

<br>
<br>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

To delete an IdP, the IdP must be first of all disabled.
Without disabling the IdP a deletion will not be offered/possible.
As soon as the IdP got disabled; the deletion can get triggered. Please note - deletions can't get reverted and will directly take place.
As soon as the IdP is disabled, the deletion can be triggered. Please note - deletions can't get reverted and will directly take place.
If there are users assigned to this IdP only, those users won't be able to login again until those users are migrated to another IdP.

<br>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,24 @@

<br>

#### What do the different IDP types stand for
#### What do the different IdP types stand for

IdP types are defined to differentiate between the different IdP owner/managed.
IdP types are defined to differentiate between the different IdPs, owned/managed.

<br>

| Type | Description | Owner | User |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Shared | IdP Instance/Tenant provided by the platform operator. Kind of managed IdP. | Platform Operator | Platform Customer |
| Own | Own company IdP connected via federation with the platform operator IdP. | CX Participant (Company which created the IdP connection - Platform Customer) | CX Participant (Company which created the IdP connection - Platform Customer) |
| Managed | IdP managed by a 3rd party for a CX dataspace participant. E.g. an IdP of an Onboarding service provider which is managing the user logins for several OSP customers. | Onboarding Service Provider (3rd Party) | CX Particpant |
| Shared | IdP Instance/Tenant provided by the platform operator. Somewhat managed IdP. | Platform Operator | Platform Customer |
| Owned | Own company IdP connected via federation with the platform operator IdP. | CX Participant (Company which created the IdP connection - Platform Customer) | CX Participant (Company which created the IdP connection - Platform Customer) |
| Managed | IdP managed by a 3rd party for a CX dataspace participant. E.g. an IdP of an Onboarding service provider which is managing the user logins for several OSP customers. | Onboarding Service Provider (3rd Party) | CX Participant |

<br>
<br>

#### Can I have multiple active IdPs?

Yes, it is possible to have multiple active IdPs - however note that it might result into an extended administrative work to manage a huge number of users across multiple IdPs. IdP owners are always requested to keep the number of active IdP connections to a minimum.
Yes, it is possible to have multiple active IdPs - however note that it might result in extended administrative work to manage a huge number of users across multiple IdPs. IdP owners are always requested to keep the number of active IdP connections to a minimum.
<br>
<br>

Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
## Open API - CX-Membership

The membership discovery endpoint is used to display/retrieve all cx network members based on the bpn.
The membership discovery endpoint is used to display/retrieve all cx network members based on the BPN.
The cx membership discovery endpoint can get triggered via technical as well as real users, if relevant roles are available.
Technical users can get generated easily via the user management:
<br>
Expand Down Expand Up @@ -28,7 +28,7 @@ n/a

###### Response Body

the string response includes all bpn's of active network members
the string response includes all BPN's of active network members

[
"string"
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
## Open API - Connector Discovery

The connector discovery endpoint can get triggered via technical as well as real users, if relevant roles are available.
The connector discovery endpoint can be triggered via technical as well as real users, if relevant roles are available.
For technical user, a company can request the user creation with the technical user creation feature inside the portal.
For details, click following link:
<br>
Expand All @@ -11,7 +11,7 @@ For details, click following link:

## Interface/API/Service Summary

The EDC/dataspace discovery interface is a CX network public available endpoint which can get used to retrieve edc endpoints and the related BPNs, as well as search for endpoints via the BPN
The EDC/dataspace discovery interface is a CX network publicly available endpoint which can get used to retrieve EDC endpoints and the related BPNs, as well as search for endpoints via the BPN

<br>
<br>
Expand All @@ -33,8 +33,8 @@ n/a

###### Request Body

The request body is expecting a list of BPNs for which the EDC endpoint should get be fetched.
The request body can be either empty or includes one or several bpns.
The request body expects a list of BPNs for which the EDC endpoint should get be fetched.
The request body can be either empty or include one or several BPNs.

<br>

Expand All @@ -61,7 +61,7 @@ or in case of a full list request
]

<br>
In case of an empty response, no edc is found for the requested BPNs
In case of an empty response, no EDC is found for the requested BPNs

<br>
<br>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ To update the company role, follow the following steps.
<br>
<br>

2nd select the resepctive required roles
2nd select the respective required roles

<p align="center">
<img width="636" alt="image" src="https://raw.githubusercontent.com/eclipse-tractusx/portal-assets/main/docs/static/change-company-role-options.png">
Expand All @@ -33,7 +33,7 @@ To update the company role, follow the following steps.
<br>
<br>

With the "Submit" selection the overlay with the change details as well as the required term & condition approval are getting displayed.
With the "Submit" selection the overlay with the change details as well as the required term & condition approval are being displayed.
If the user approved all the necessary T&Cs the role change can get committed and will get effective in the same moment

<p align="center">
Expand Down
2 changes: 1 addition & 1 deletion docs/user/02. Technical Integration/index.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Technical Integration

The technical integration covers functionalities such as the connector registration of an company, as well as identity provider connections. Mainly those functionalities are managed by IT Managers of an company.
The technical integration covers functionalities such as the connector registration of a company, as well as identity provider connections. Mainly those functionalities are managed by IT Managers of an company.
Learn how to configure the technical integration items in the Catena-X Portal.
Read more details in the following sections:

Expand Down

0 comments on commit d1d321a

Please sign in to comment.