====== IdM-Portal documentation ======


===== Overview =====

This page serves as an introduction for the use of the Identity Management portal (IDM-portal).

{{:en:services:general_services:idm:login.png?600|}}

The site is available at [[https://portal.idm.gwdg.de]]. Log in is possible via Single Sign-on (SSO). The portal is available in english or german. The language can be changed in the top right corner.

===== Access requirements =====
Every GWDG/academiccloud account can login, but may have not the required set of permissions to do certain tasks. Please see: https://portal.idm.gwdg.de/docs/authorization for further information (login required).

===== FAQ =====
**Q: ** I would like to manage user accounts, but after login I can only see my own account details and nothing else. What to do? \\
** A: ** Your account lacks the required permissions. Please refer to https://portal.idm.gwdg.de/docs/authorization or email to: [[support@gwdg.de?subject=Permissions for IDM-Portal|support@gwdg.de]]

**Q: ** When I log in I get a strange "Permission downgrade" message. What does that mean?\\
** A: ** For one or all of your permissions are "allowed networks" configured. Which means you can log in but your current portal session does not get these permissions assigned. Please check that you are connected to your institutional network or have a VPN session active.

**Q: ** I would like to export all search results but the export file only shows n records. What is wrong? \\
** A: ** Unfortunately that is a known bug and will be addressed in the future. As a workaround you can increase the search result page size in your personal settings and do the export once again.

** Q: ** I would like to have a group whose members are based on a certain criterion such as the department name. How can I achieve that?\\
** A: ** See: [[#dynamic_group|Dynamic group]]

** Q: ** I would like to have an easy way to get members into certain groups. Is there a way not to add everyone manually?\\
** A: ** See: [[#invitation|Invitation]]


===== Site structure and navigation =====

{{:en:services:general_services:idm:bild_2024-08-28_082833704.png?600|}}

After a successful login the site has two navigation menus. On the upper side the first item is a dropdown menu which lets you switch to another so called //workspace// (1). The menu on the left side is always correlated to the currently selected //workspace// (2). If you have the permission another item is available in the upper menu which lets you start an approval process (3). See [[#Approval Process|Approval Process]] for further infos.

<WRAP center round info 60%>
**Workspace**  \\
A //workspace// is a logical set of configuration values which define what objects you can find/edit/create and so on. For example the //workspace// called **Benutzerverwaltung** is all about user identities and actions related to them. In **Gruppenverwaltung** on the other hand you can manage group objects and their members.
</WRAP>

===== User management =====
==== Search ====


The search function allows you to find objects in the currently selected workspace. Default is the //simple search// where you can enter any text and the portal executes a search based on certain attributes like uid/e-mail/displayname etc. (1)\\

If you wish to search for objects based on specific attributes like username, e-mail address, user status etc., you can use the **Advanced Search**, which is located in the second tab (2).\\
\\
For a more complex search, you can append multiple search rows by clicking the **dropdown** on the right hand side next to the input field. These search rows are linked by **and** or **or**, as shown at the end of the search row on the right side. By clicking on the button, you can toggle between those two options.\\

{{:en:services:general_services:idm:bild_2024-08-28_083244533.png?600|}}

{{:en:services:general_services:idm:bild_2024-08-28_083510932.png?600|}}

<WRAP center round info 60%>
The * character can be used as a wildcard, but only with the operator: **equal**.
You can use **"username equal *"** if you want to find all available objects.
</WRAP>

<WRAP center round info 60%>
You will be redirected to the edit page if only one object was found.
</WRAP>

The search result list contains a subset of the objects attributes. The shown attributes can be customized in the [[idm-portal_documentation#personal settings|personal settings]].

After switching to the edit page, new actions specific to the currently selected object appear on the left side menu ((may vary based on your permissions)). Attributes of a selected object are categorized into groups like **general user data** or **Email**.

{{:en:services:general_services:idm:bild_2024-08-27_101021058.png?600|}}

==== Password change ====
On this page you can change the password of a user account. The password has an expiration date which means that the user must change the password within this period or the account gets deactivated (1). A short description text why the change was necessary must be entered (2). This text will be logged in the audit log for future reviews.

The password must meet a series of requirements which are listed above. These requirements are not arbitrary, but rather forced by connected system like Microsoft Active Directory or SAP which dictate these.

<WRAP center round info 60%>
Users can change their password using the self service portal: https://id.academiccloud.de 
</WRAP>

{{:en:services:general_services:idm:bild_2024-08-27_112438707.png?600|}}

{{:en:services:general_services:idm:bild_2024-08-28_083825984.png?600|}}

You can also generate a random password by clicking the **generate** button (3). You must **save** or **save & print** the password afterwards. 

{{:en:services:general_services:idm:bild_2024-08-28_084258073.png?600|}}

A PDF document will be generated and opened if you choose **save and print**.
<WRAP center info 60%>
The template for the generated PDF file can be set individually for each institution. If you desire to use a non-standard template, write a mail to support@gwdg.de. The template should be created in the docx format. As placeholders the following values can be used: first name, last name, username, password
</WRAP>


=== Password expiration ===

^ Organization ^ Expiration ^ Notification ^
|UNI| no | 1 year |4 weeks before expiration weekly, \\ 7 days before expiration daily|
|MPG| no | never or upon request |  |


==== History ====
{{:en:services:general_services:idm:bild_2024-08-28_084558773.png?600|}}

By clicking the **history** action, attribute and password changes can be reviewed. Changes that were made by the system are marked as //(idm-internal)//. The second tab shows the login history of the object, if applicable.

==== Personal settings ====


The personal settings menu allows you to change how search results are displayed. You can find the Personal Settings page by opening the menu with the profile icon in the upper right corner. You can add and remove attributes in the list to change the layout of the search result table. You must change these settings for each workspace separately.

{{:en:services:general_services:idm:bild_2024-08-28_084723477.png?600|}}

{{:en:services:general_services:idm:bild_2024-08-28_084831490.png?600|}}

==== Special attribute descriptions ====

=== Email forwarding ===

Two attributes can be used to forward incoming mails: **routing addresses** and **exchange redirect address**. If the user has an exchange mailbox you should use the exchange redirect address, otherwise use routing addresses. 

^ Name ^ Multiple values ^ Forward internal sent emails   ^
| routing addresses     | yes    | no |
| exchange redirect address     |no   | yes |

<WRAP center round important 60%>
If the source and the target mailbox are within the same Exchange organization the mail is delivered directly into the target mailbox which prevents the **routing addresses** attribute from taking effect.
</WRAP>

=== Visibility in Exchange addressbook ===
By default, all users are displayed in the Exchange address lists. To change this setting check the **hide from address lists** checkbox. <WRAP center round info 60%>
When using the Exchange cache mode with an Outlook client, the updating of the address book can take up to 48 hours. Outlook Web Access under https://email.gwdg.de instantly shows the changed settings.
</WRAP>

=== Remove Active Directory short time lockout ===
The Active Directory automatically locks a user account for a certain time (usually 30 minutes) if the password is entered incorrectly for 3 times. To remove this lock the corresponding ** short time lockout (AD) ** checkbox must be unchecked.

=== Enable/Disable ===
You can enable and disable accounts by changing the **user status**.
Send an email to [[support@gwdg.de]] if you want to reactivate a deleted account. 

<WRAP center round info 60%>
Applicable to Uni Göttingen accounts only: The account status is linked to the employment in SAP. As soon as the employment is active again a deleted account is also reactivated.
</WRAP>




===== Group management =====

Currently there are two different types of distribution lists:

**LDAP distribution list**
  * May contain external email addresses
  * Not visible in the Exchange addressbook

**Groups**
  * Can act as a Static Exchange distribution group 
  * Visible in the Exchange addressbook
  * Members are shown in addressbook
  * Send permissions can be defined
  * Editing can be limited to certain user

==== Groups ====

If you don't provide an email address, groups are just a structural organisation tool. When an email address is given, they turn into an exchange distribution group. 

When 'Only editable by "Managed by"' is checked, editing of the group is limited to the selected users. It takes a couple of minutes for the permission to be distributed to the accounts. A user account entered as managed by needs to logout and login again to gain these new permissions.

<WRAP center round important 60%>
Be aware that 'managed by' can exclude and lock out the creator of the group. Avoid to add other groups as 'managed by'. Privileges for editing are not derived to their members.
</WRAP>

<WRAP center round important 60%>
Be aware that deleting a group is immediate and cannot be recovered.
</WRAP>


=== Add / Remove members ===
There are two ways to add accounts to the group:
  * By clicking the **Add** button and insert the username or email address (1).
  * By clicking the **Select** button (2). A modal dialog is opened with all accounts to which one is entitled to ((For certain accounts with too much permissions this may not work because the result set is too large. This is a known limitation. Please use "add" instead.)).

Members can be removed by selecting them in the table and clicking on **remove**.

{{:en:services:general_services:idm:bild_2024-08-27_140203630.png?600|}}
=== Send permissions ===
You can set send permissions to control who can send to the list.
Users who are not allowed will receive a notification email if they try to send to the list.
You can choose between different settings:
  * Unrestricted or as specified (default): Everybody is allowed to send to the list if the send permission list is empty. Otherwise, only the specified users/groups are allowed to send to the list.
  * Organization: All users of your organization with an Exchange mailbox or email enabled users are allowed to send to the list.
  * Institute: All users of your institution with an Exchange mailbox or email enabled users are allowed to send to the list.

=== Group visibility ===
You can set the visibility of the group for certain connected services. In this case the information of the group is synchronized to the service accordingly. For example if the visibility for Matrix is set, the Group ist created in Matrix having the appropriate member.
=== Dynamic group ===
An ordinary group can be turned into a dynamic group by adding a filter expression. This filter expression specifies which attribute values an object needs to have to be part of this group (e.g. all objects with the attribute "department" set to "A"). 

<WRAP center round tip 80%>
You can easily create a distribution group for all members (normal user) of the department "AG I" by using the filter:

''$usertype -eq '0' -and $department -eq 'AG I' ''

All new staff will automatically be added to this group if the department is set to **AG I**."
</WRAP>

<WRAP center round important 80%>
When using multiple filters be aware of logical interpretations of those filters and its grouped components.
Using parentheses might be very useful or even necessary! 

For example: Addressing all normal user in two departments.

**Wrong**: just lining up each expression:

''$usertype -eq '0' -and $department -eq 'AG I' -or $department -eq 'AG O' ''

This will address all normal users for the department 'AG I' but for 'AG O' it will also address all other possible user types (**including distribution lists**).

**Correct**: To ensure only normal users are addressed in both departments the conditions need to be separated and grouped.

''$usertype -eq '0' -and ($department -eq 'AG I' -or $department -eq 'AG O')''

or, without parentheses, be defined for each condition:

''$usertype -eq '0' -and $department -eq 'AG I' -or $usertype -eq '0' -and $department -eq 'AG O' ''

</WRAP>

The Filter uses the OPath-Syntax: <wrap hi>$variablename -operator 'value'</wrap>.\\ 
You can use parentheses for complex filters as well.

**Supported variables**
^ Variable           ^ Description                                                                                                                                                     ^
| $goesternid        | Goestern id of an object. Can be found in the details of an object for instance groups. For example: $goesternid -eq 'GOESTERN-0121212'                         |
| $department        | Department                                                                                                                                                      |
| $title             | Job title                                                                                                                                                       |
| $usertype          | User type (0 = normal user, 1 = time based user, 2  = course user, 4 = function account)                                                                        |
| $userstatus        | User status (0 = active, 1 = disabled, 2 = delete)                                                                                                              |
| $gender            | Gender: Valid values are (M/W/D), for example: $gender -eq 'W'                                                                                                  |
| $institute         | Institution (example: $institute -eg 'MMDL') as an indication see the four characters, parenthesized value of the attribute "institute" of groups and/or users  |
| $filterattribute1  | User defined attribute                                                                                                                                          |
| $filterattribute2  | User defined attribute                                                                                                                                          |
| $filterattribute3  | User defined attribute                                                                                                                                          |
| $emailaddresses    | EMail addresses have to be defined in the following way, for example: $emailaddresses -eq 'example@gwdg.de' or $emailaddresses -like '*@mail.gwdg.de'           |

**Valid operators**
^ Operator  ^ Description                      ^
| -eq       | Equal                            |
| -ne       | Not equal                        |
| -like     | Like (a wildcard '*' is needed)  |
| -and      | And                              |
| -or       | Or                               |
| -not      | Not                              |

== Group Member Scope ==
Defines the scope where to find the member. Possible values are institute and organization. Default scope is organization.

== Attribute name for determining members == 
A group member filter can match other groups. These groups eventually have members. To use the members of these found groups as "effective members" and activate this "two step processing mode" you can configure an attribute name.

<WRAP center round important 80%>
When an //Attribute name for determining members// is set, only members of the found objects, selected by the filter, are considered. 
Additional members can be added using the //Additional Members// attribute. Combining the selection of users and groups is not supported.
</WRAP>

Example:
<code>
Group: GOESTERN-0123456 has 
1. "member" as attribute name for determining members configured and 
2. the following filter: "( $cn -eq 'GOESTERN-0121212' ) -or ( $cn -eq 'GOESTERN-0131313' )"              
         │                                                                      
filter   │                                                                      
matches  │                                                                      
these    ├──────►  Group: GOESTERN-0121212                                      
two      │                                                                      
groups   │                member: GOESTERN-01....  │         GOESTERN-01....    
         │                        GOESTERN-02....  │         GOESTERN-02....    
         │                        GOESTERN-03....  ├─────────GOESTERN-03....    
         │                                         │         GOESTERN-04....    
         └───────► Group: GOESTERN-0131313         │         GOESTERN-05....    
                                                   │         GOESTERN-06....    
                          member: GOESTERN-04....  │               │            
                                  GOESTERN-05....  │               │            
                                  GOESTERN-06....  │               │            
                                                                   │            
                                                                   │            
                                                            Effective members of
                                                            GOESTERN-0123456       
</code>

== Additional Members ==
List of members/account additionally appended to the group after calculating the dynamic members.

== Excluded Members ==
List of members/accounts removed from the group, when contained, after calculating the dynamic members.

== Error during member calculation ==
The background process calculating the group members indicates errors by setting a value into an attribute called //Group Calculation error//. If a value is set, it **prevents** new calculations from running. Setting the value manually prevents further calculations as well.
The value for //Group Calculation error// needs to be removed to resume the calculation.
The containing text gives details of the problem: For example: 
  * The calculated member count (352) exceeds the defined member limit (80)
  * The calculated member count changed from exceeding the threshold (100) to 0; implies filter error


Sometimes a syntactically correct, but logically invalid search filter is entered. To mitigate the negative effects of dropping from **n** members to **0** a further check is implemented: If the last run resulted in more than 100 members and the new run results in 0 members, an update is blocked.

=== Invitation ===
For groups an invitation link can be created. You can distribute this link (e.g. by email) and thus easily enable others to become members.

{{:en:services:general_services:idm:bild_2024-08-27_152808001.png?600|}}

{{:en:services:general_services:idm:bild_2024-08-27_152923922.png?600|}}

{{:en:services:general_services:idm:bild_2024-08-27_152959991.png?600|}}

=== Limits ===
You can configure a maximum upper limit on how many accounts are member of a group. This can be useful if the group is used for license assignments.

The limit also matches for dynamic groups. If a new member calculation would add more members as the upper limit, the run is cancelled and //Group Calculation error// is set accordingly.

{{:en:services:general_services:idm:bild_2024-08-28_115438511.png?600|}}

===== Approval process =====
You may have only access to create certain new object types through the //approval process// ((This is dependent on your institution and may not be available at all)). A request for a new account/group/resource etc. must be created first. Then a group of approvers get notified via email that this request has been created and can decide to accept or reject. If the request is accepted the applicant is notified with yet another mail.


{{:en:services:general_services:idm:bild_2024-08-28_085023230.png?600|}}

{{:en:services:general_services:idm:bild_2024-08-28_085140704.png?600|}}

===== Shared mailboxes =====
TODO

===== Resource mailboxes =====
TODO




===== Application Credentials =====
The Application Credentials page allows you to create Credentials for your account that work for a certain service only. You can think of them as sub-accounts to your account.

You can find the Application Credentials via the profile menu.

{{:en:services:general_services:idm:bild_2024-08-28_085239967.png?600|}}

Select a service you want to add credentials for, for example the //IdM API//. After creating a new Application Credential, you will be able to use it with the specified service only, and you can deactivate or delete the Application Credential at any time.

{{:en:services:general_services:idm:bild_2024-08-28_085345012.png?600|}}


See: https://gwdg.de/about-us/gwdg-news/2023/GN_3-2023_www.pdf for detailed infos of motivations and use cases.

===== API =====
See: https://portal.idm.gwdg.de/docs (login required)