'\" te
.\" Copyright (c) 2007, 2015, Oracle and/or its affiliates. All rights    reserved.
.TH pam_roles 5 "16 Jun 2015" "SunOS 5.11" "Standards, Environments, and Macros"
.SH NAME
pam_roles \- Solaris Roles account management module
.SH SYNOPSIS
.LP
.nf
pam_roles.so.1
.fi

.SH DESCRIPTION
.sp
.LP
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(4) database is used to determine which users can assume which roles.
.sp
.LP
The \fBPAM\fR items \fBPAM_USER\fR and \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(5) module.
.sp
.LP
The following options are interpreted:
.sp
.ne 2
.mk
.na
\fB\fBallow_remote\fR\fR
.ad
.RS 16n
.rt  
Allows a remote service to specify the user to enter as a role.
.RE

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

.SH ERRORS
.sp
.LP
The following values are returned:
.sp
.ne 2
.mk
.na
\fB\fBPAM_IGNORE\fR\fR
.ad
.RS 20n
.rt  
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
.mk
.na
\fB\fBPAM_USER_UNKNOWN\fR\fR
.ad
.RS 20n
.rt  
No account is present for user.
.RE

.sp
.ne 2
.mk
.na
\fB\fBPAM_PERM_DENIED\fR\fR
.ad
.RS 20n
.rt  
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
.LP
\fBExample 1 \fRUsing the \fBpam_roles.so.1\fR Module
.sp
.LP
The following example is a \fBpam.conf\fR(4) fragment that demonstrates 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 equivalent configuration in \fB/etc/pam.d/\fR would be the following entry in \fB/etc/pam.d/cron\fR:

.sp
.in +2
.nf
account required pam_unix_account.so.1
.fi
.in -2
.sp

.sp
.LP
and the following entries in \fB/etc/pam.d/other\fR:

.sp
.in +2
.nf
account requisite pam_roles.so.1
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\fR-hostbased).

.sp
.LP
The following example is a \fBpam.conf\fR(4) fragment that 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

.sp
.LP
The equivalent configuration in \fB/etc/pam.d/\fR would be the following entries in \fB/etc/pam.d/sshd-hostbased\fR:

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

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

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT LevelMT-Safe with exceptions
.TE

.SH SEE ALSO
.sp
.LP
\fBroles\fR(1), \fBsshd\fR(1M), \fBsu\fR(1M), \fBlibpam\fR(3LIB), \fBpam\fR(3PAM), \fBpam_acct_mgmt\fR(3PAM), \fBpam_setcred\fR(3PAM), \fBpam_set_item\fR(3PAM), \fBpam_sm_acct_mgmt\fR(3PAM), \fBsyslog\fR(3C), \fBpam.conf\fR(4), \fBuser_attr\fR(4), \fBattributes\fR(5), \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), \fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5), \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), \fBpam_unix_session\fR(5)
.SH NOTES
.sp
.LP
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\fR-hostbased). 
.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).