'\" te
.\" Copyright (C) 2007, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH PAM_ROLES 7 "August 19, 2023"
.SH NAME
pam_roles \- Roles account management module
.SH SYNOPSIS
.nf
pam_roles.so.1
.fi

.SH DESCRIPTION
The \fBpam_roles\fR module implements \fBpam_sm_acct_mgmt\fR(3PAM). It provides
functionality to verify that a user is authorized to assume a role. It also
prevents direct logins to a role. The \fBuser_attr\fR(5) database is used to
determine which users can assume which roles.
.sp
.LP
The \fBPAM\fR items \fBPAM_USER\fR, \fBPAM_AUSER\fR, and \fBPAM_RHOST\fR are
used to determine the outcome of this module. \fBPAM_USER\fR represents the new
identity being verified. \fBPAM_AUSER\fR, if set, represents the user asserting
a new identity. If \fBPAM_AUSER\fR is not set, the real user \fBID\fR of the
calling service implies that the user is asserting a new identity. Notice that
root can never have roles.
.sp
.LP
This module is generally stacked above the \fBpam_unix_account\fR(7) module.
.sp
.LP
The following options are interpreted:
.sp
.ne 2
.na
\fB\fBallow_remote\fR\fR
.ad
.RS 16n
Allows a remote service to specify the user to enter as a role.
.RE

.sp
.ne 2
.na
\fB\fBdebug\fR\fR
.ad
.RS 16n
Provides \fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level.
.RE

.SH ERRORS
The following values are returned:
.sp
.ne 2
.na
\fB\fBPAM_IGNORE\fR\fR
.ad
.RS 20n
If the type of the new user identity (\fBPAM_USER\fR) is "\fBnormal\fR". Or, if
the type of the new user identity is "\fBrole\fR" and the user asserting the
new identity (\fBPAM_AUSER\fR) has the new identity name in its list of roles.
.RE

.sp
.ne 2
.na
\fB\fBPAM_USER_UNKNOWN\fR\fR
.ad
.RS 20n
No account is present for user.
.RE

.sp
.ne 2
.na
\fB\fBPAM_PERM_DENIED\fR\fR
.ad
.RS 20n
If the type of the new user identity (\fBPAM_USER\fR) is "\fBrole\fR" and the
user asserting the new identity (\fBPAM_AUSER\fR) does not have the new
identity name in its list of roles.
.RE

.SH EXAMPLES
\fBExample 1 \fRUsing the \fBpam_roles.so.1\fR Module
.sp
.LP
The following are sample entries from \fBpam.conf\fR(5). These entries
demonstrate the use of the \fBpam_roles.so.1\fR module:

.sp
.in +2
.nf
cron account required pam_unix_account.so.1
#
other account requisite pam_roles.so.1
other account required pam_unix_account.so.1
#
.fi
.in -2
.sp

.sp
.LP
The \fBcron\fR service does not invoke \fBpam_roles.so.1\fR. Delayed jobs are
independent of role assumption. All other services verify that roles cannot
directly login. The "\fBsu\fR" service (covered by the "\fBother\fR" service
entry) verifies that if the new user is a role, the calling user is authorized
for that role.

.LP
\fBExample 2 \fRAllowing Remote Roles
.sp
.LP
Remote roles should only be allowed from remote services that can be trusted to
provide an accurate \fBPAM_AUSER\fR name. This trust is a function of the
protocol (such as \fBsshd-hostbased\fR).

.sp
.LP
The following is a sample entry for a \fBpam.conf\fR(5) file. It demonstrates
the use of \fBpam_roles\fR configuration for remote roles for the
\fBsshd-hostbased\fR service.

.sp
.in +2
.nf
sshd-hostbased account requisite pam_roles.so.1 allow_remote
sshd-hostbased account required pam_unix_account.so.1
.fi
.in -2
.sp

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
_
MT Level	MT-Safe with exceptions
.TE

.SH SEE ALSO
.BR roles (1),
.BR syslog (3C),
.BR libpam (3LIB),
.BR pam (3PAM),
.BR pam_acct_mgmt (3PAM),
.BR pam_set_item (3PAM),
.BR pam_setcred (3PAM),
.BR pam_sm_acct_mgmt (3PAM),
.BR pam.conf (5),
.BR user_attr (5),
.BR attributes (7),
.BR pam_authtok_check (7),
.BR pam_authtok_get (7),
.BR pam_authtok_store (7),
.BR pam_dhkeys (7),
.BR pam_passwd_auth (7),
.BR pam_unix_account (7),
.BR pam_unix_auth (7),
.BR pam_unix_session (7),
.BR sshd (8),
.BR su (8)
.SH NOTES
The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the
multi-threaded application uses its own \fBPAM\fR handle.
.sp
.LP
This module should never be stacked alone. It never returns \fBPAM_SUCCESS\fR,
as it never makes a positive decision.
.sp
.LP
The \fBallow_remote\fR option should only be specified for services that are
trusted to correctly identify the remote user (that is, \fBsshd-hostbased\fR).
.sp
.LP
\fBPAM_AUSER\fR has replaced \fBPAM_RUSER\fR whose definition is limited to the
\fBrlogin\fR/\fBrsh\fR untrusted remote user name. See
\fBpam_set_item\fR(3PAM).