설치 및 업그레이드 > ThingWorx 설치 > 보안 구성 > SSO(Single Sign-On) 인증 > SSO(Single Sign-On)에 대한 ThingWorx 구성 > sso-settings.json 파일 구성
sso-settings.json 파일 구성
ssoSecurityConfig 디렉터리에서 sso-settings.json 파일을 생성합니다.
사용자의 환경에 다른 경로가 필요한 경우 sso-settings.json 파일을 다른 위치에 저장하도록 THINGWORX_SSO_SETTINGS 환경 변수의 값을 설정합니다.
다음은 sso-settings.json 파일의 샘플 구조입니다.
{
"BasicSettings": {
"clientBaseUrl": "아래 표의 정보 참조",
"idpMetadataFilePath": "아래 표의 정보 참조",
"metadataEntityId": "아래 표의 정보 참조",
"metadataEntityBaseUrl": "아래 표의 정보 참조",
"webSSOProfileConsumerResponseSkew": "아래 표의 정보 참조",
"webSSOProfileConsumerReleaseDOM": "아래 표의 정보 참조",
"webSSOProfileResponseSkew": "아래 표의 정보 참조",
"retriggerOnScopesRemoval": "아래 표의 정보 참조",
"samlAssertionUserNameAttributeName": "아래 표의 정보 참조",
"samlAssertionMaxAuthenticationAge": "아래 표의 정보 참조",
"ptcOperatorsGroupName": "아래 표의 정보 참조",
"samlGroupClaimName": "아래 표의 정보 참조",
"administratorAlias": "아래 표의 정보 참조",
“administratorInternalName": "Administrator",
"authnContextAsPassword": "아래 표의 정보 참조",
"authenticationType": "아래 표의 정보 참조
},
"AccessTokenPersistenceSettings": {
"dbType": "아래 표의 정보 참조",
"driverClassName": "아래 표의 정보 참조",
"url": "아래 표의 정보 참조",
"username": "아래 표의 정보 참조",
"password": "아래 표의 정보 참조",
"encryptTokenInDatabase": "아래 표의 정보 참조",
},
"KeyManagerSettings": {
"keyStoreFilePath": "아래 표의 정보 참조",
"keyStoreStorePass": "아래 표의 정보 참조",
"keyStoreKey": "아래 표의 정보 참조",
"keyStoreKeyPass": "아래 표의 정보 참조"
},
"AuthorizationServersSettings": {
"<AuthorizationServerId1>": {
"clientId": "아래 표의 정보 참조",
"clientSecret": "아래 표의 정보 참조",
"authorizeUri": "아래 표의 정보 참조",
"tokenUri": "아래 표의 정보 참조",
"clientAuthScheme": "아래 표의 정보 참조"
},
"<AuthorizationServerId2>": {
"clientId": "아래 표의 정보 참조",
"clientSecret": "아래 표의 정보 참조",
"authorizeUri": "아래 표의 정보 참조",
"tokenUri": "아래 표의 정보 참조",
"clientAuthScheme": "아래 표의 정보 참조"
"mandatoryScopes": "아래 표의 정보 참조"
},
"OIDCSettings": {
"accessTokenClaimsValidation":"아래 표의 정보 참조",
"additionalScopes": "아래 표의 정보 참조",
"assertionUserNameAttributeName": "아래 표의 정보 참조",
"clientId": "아래 표의 정보 참조",
"clientSecret": "아래 표의 정보 참조",
"openIdConfigurationUri": "아래 표의 정보 참조",
"proxyAuthentication": "아래 표의 정보 참조",
"useAccessTokenClaims": "아래 표의 정보 참조"
},
"AzureSettings": {
"apiEndPoint": "아래 표의 정보 참조"
}
}
* 
모든 매개 변수의 값을 사용자의 요구사항에 따라 편집해야 합니다. 구현은 ThingWorx가 호스팅된 위치, 조직의 보안 정책, 페더레이션에 대한 CAS 등 여러 요인에 따라 다를 수 있습니다. 다음 표의 정보를 지침으로 사용하여 서로 다른 매개 변수의 값을 설정합니다.
다음 표에서는 sso-settings.json 파일에 있는 BasicSettings 섹션의 서로 다른 매개 변수와 기본값을 설명합니다.
매개 변수
설명
값
clientBaseUrl
ThingWorx 서버 인스턴스의 URL을 지정합니다.
이 URL을 ThingWorx 서버의 전체 도메인 이름(FQDN)으로 설정합니다.
HA(고가용성) 환경에서 작동하도록 ThingWorx를 구성한 경우 부하 분산의 호스트 및 포트를 지정합니다.
http://<ThingWorx-FQDN>:<port-number>/Thingworx
또는
고가용성 환경에서 https://<부하 분산 호스트 이름>:<부하 분산 포트 번호>/Thingworx
idpMetadataFilePath
SAML 인증인 경우에만 필수입니다. IdP 메타데이터 파일의 절대 파일 경로 위치를 지정합니다.
/ThingworxPlatform/ssoSecurityConfig/sso-idp-metadata.xml
metadataEntityId
SAML 인증인 경우에만 필수입니다. 서비스 공급자 연결의 엔티티 ID를 지정합니다.
• PingFederate를 CAS로 사용: 서비스 공급자 연결을 구성할 때 선택한 고유한 ID를 사용합니다.
• Microsoft Entra ID를 CAS로 사용: 기본 SAML 설정을 구성할 때 정의한 Identifier (Entitity ID)를 사용합니다.
• AD FS를 CAS로 사용: 신뢰 당사자 트러스트 설정을 구성할 때 정의한 Relying party trust identifier를 사용합니다.
—
metadataEntityBaseUrl
SAML 인증인 경우에만 필수입니다. ThingWorx 서버의 전체 도메인 이름을 지정합니다.
* 
정규화되지 않은 도메인 이름은 사용하지 않는 것이 좋습니다. 조직에서 전체가 아닌 도메인 이름을 사용하도록 선택한 경우 IT 부서에서는 도메인 이름이 클라이언트 시스템에서 액세스할 수 있으며 ThingWorx SSO 구성 파일 내에서 정확하게 구성되었는지 확인해야 합니다.
HA(고가용성) 환경에서 작동하도록 ThingWorx를 구성한 경우 부하 분산의 호스트 및 포트를 지정합니다.
http://<ThingWorx-FQDN>:<port-number>/Thingworx
또는
고가용성 환경에서 https://<부하 분산 호스트 이름>:<부하 분산 포트 번호>/Thingworx
webSSOProfileConsumerResponseSkew
SAML 2.0 WebSSO 어설션 소비자 응답 스큐 공차를 지정합니다.
이 값을 설정할 때 사용자 자신의 보안 요구사항뿐만 아니라 엔터프라이즈 네트워크에서의 대기 시간도 고려하십시오.
이 설정을 사용하여 CAS의 로그인 요청 응답을 ThingWorx로 반환하는 데 허용된 시간(초)을 설정합니다. 로그인 요청 응답이 이 값보다 더 오래 걸리는 경우 로그인 시도가 실패합니다.
스큐 공차는 시스템 클럭 간의 추정된 차이로 인해 수신자가 허용하는 응답 유효성의 편차입니다. 관련된 각 시스템의 클럭이 제대로 동기화되도록 지정함으로써 스큐의 영향을 최소화하는 것이 가장 좋습니다.
300
webSSOProfileConsumerReleaseDOM
인증이 완료된 후 보안 프레임워크가 SAML 어설션을 유지하는지 여부를 결정합니다.
false로 설정하면 인증 완료 후 SAML 어설션이 유지됩니다.
true
webSSOProfileResponseSkew
SAML 2.0 Web SSO 프로파일 응답 스큐 공차를 지정합니다.
이 값을 설정할 때 사용자 자신의 보안 요구사항뿐만 아니라 엔터프라이즈 네트워크에서의 대기 시간도 고려하십시오.
스큐 공차는 시스템 클럭 간의 추정된 차이로 인해 수신자가 허용하는 응답 유효성의 편차입니다. 관련된 각 시스템의 클럭이 제대로 동기화되도록 지정함으로써 스큐의 영향을 최소화하는 것이 가장 좋습니다.
300
retriggerOnScopesRemoval
필수 범위 목록이 변경되어서 새로 고쳐야 하는지를 지정합니다.
값이 true로 설정되면 필수 범위 목록에서 범위가 추가 또는 제거되었음을 나타냅니다.
값이 false로 설정되면 필수 범위 목록에 범위가 추가되었음을 나타냅니다.
true
samlAssertionUserNameAttributeName
SAML 인증인 경우에만 필수입니다. ThingWorx 사용자가 로그인할 때 해당 사용자 이름을 저장하는 값을 전달하는 SAML 속성을 지정합니다. ID 공급자에서 이 속성의 값이 ThingWorx 사용자 이름에 대해 사용할 사용자 이름 값과 정렬되는지 확인합니다.
* 
ThingWorx 관리자 계정의 경우 사용자 이름 값이 Administrator로 설정되어야 합니다. 관리자 계정에 대해 Administrator 값을 반환하도록 IdP를 구성해야 합니다. 자세한 내용은 ID 공급자에서 ThingWorx 관리자 별칭 생성을 참조하십시오.
• PingFederate 또는 Microsoft Entra ID를 CAS로 사용:
uid
• AD FS를 CAS로 사용:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
samlAssertionMaxAuthenticationAge
SAML 인증인 경우에만 필수입니다. SAML 2.0 어설션이 만료되기 전 최대 기간(초)을 지정합니다. 이는 인증 어설션에 대한 최대 세션 시간도 지정합니다.
값을 ID 공급자에 지정된 세션 제한 시간 값과 일치하도록 설정합니다. 이 값은 사용 중인 IdP에 따라 달라집니다.
• PingFederate를 CAS로 사용(LDAP IdP 사용)(Windchill): 7200(기본값)
• AD FS를 IdP로 사용(AD FS 또는 PingFederate를 CAS로 사용): 28800
• Microsoft Entra ID를 IdP로 사용(Microsoft Entra ID 또는 PingFederate를 CAS 사용): 86400
ptcOperatorsGroupName
선택 사항.
IDP에서 정의된 대로 그룹을 자동으로 ThingWorx 관리자 그룹에 포함되도록 구성하려면 이 매개 변수를 설정합니다.
administratorAlias
OIDC 인증의 경우 필수입니다.
CAS[IDP]에 구성된 관리자 사용자 이름입니다.
administratorInternalName
administratorAlias가 정의된 경우 필수입니다.
ThingWorx에서 구성된 관리자 사용자 이름입니다. 예를 들어, Administrator입니다.
samlGroupClaimName
선택 사항이지만 SAML 인증인 경우에만 필수입니다.
이 매개 변수는 ptcOperatorsGroupName이 정의된 경우에만 관련됩니다.
CAS에 구성된 IDP SAML Group Claim Name을 입력하여 ThingWorx SSO Authenticator에서 해당 그룹에 대한 자동화를 완료합니다. 자세한 내용은 ThingworxSSOAuthenticator를 참조하십시오.
예:
PingFederate CAS의 경우: group
authnContextAsPassword
선택 사항. 드물지만 IdP에서 다음 어설션을 SAML 요청에 넣어야 하는 경우도 있습니다.
<saml2p:RequestedAuthnContext Comparison="exact">
<saml2:AuthnContextClassRef xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
urn:oasis:names:tc:SAML:2.0:ac:classes:Password
</saml2:AuthnContextClassRef>
</saml2p:RequestedAuthnContext>
이러한 경우에는 이 속성을 정의해야 합니다.
false
authenticationType
선택 사항. 인증 유형: oidc/saml. 기본값 = saml
PingFederate 및 ADFS에 필요하지 않음(SAML이 기본값이므로)
Microsoft Entra ID의 경우 – saml/oidc
Azure AD B2C 및 Atlas IAM의 경우 - oidc
* 
SSO가 활성화될 때 응용 프로그램 키 인증자를 활성화하려면 다음 ApplicationKeySettings 구성 섹션을 BasicSettings의 sso-settings.json 설정에 추가해야 합니다. REST API 요청을 통한 인증에 응용 프로그램 키를 사용하려는 경우에만 이렇게 해야 합니다. 이 설정의 활성화 여부에 상관없이 WebSocket을 통해 에지 장치에서 응용 프로그램 키를 계속 사용할 수 있습니다.
{
"BasicSettings": {
...
},
"ApplicationKeySettings": {
"enabled": true
},
...
}
다음 표에서는 sso-settings.json 파일에 있는 AccessTokenPersistenceSettings 섹션의 서로 다른 매개 변수와 기본값을 설명합니다.
매개 변수
설명
값
dbType
ThingWorx 설치용으로 구성되고 사용되는 데이터베이스 유형을 지정합니다.
• platform-settings.json 파일에 설정된 것과 동일한 데이터베이스를 사용하려면 platform-settings.json에 설정된 것과 동일한 데이터베이스 유형 및 자격 증명을 지정합니다.
postgres
mssql
driverClassName
platform-settings.json 파일에서 사용할 드라이버 클래스 이름을 지정합니다.
postgres로 설정된 dbType의 경우 org.postgresql.Driver로 설정합니다.
mssql로 설정된 dbType의 경우 com.microsoft.sqlserver.jdbc.SQLServerDriver로 설정합니다.
url
ThingWorx 설치를 위한 데이터베이스 위치의 URL을 지정합니다.
postgres로 설정된 dbType의 경우 jdbc:postgresql://<hostname>:<port>/thingworx로 설정합니다.
mssql로 설정된 dbType의 경우 jdbc:sqlserver://<hostname>:<port>;databaseName=thingworx;applicationName=Thingworx로 설정합니다.
username
액세스 토큰을 저장하기 위해 시스템에서 사용하는 데이터베이스에 대한 사용자 이름을 지정합니다. 이는 platform-settings.json 파일에서 지정한 사용자 이름과 일치해야 합니다.
—
password
액세스 토큰을 저장하기 위해 시스템에서 사용하는 데이터베이스에 대한 암호를 지정합니다. 이는 platform-settings.json 파일에서 지정한 암호와 일치해야 합니다.
—
encryptTokenInDatabase
액세스 토큰을 암호화한 다음 데이터베이스에서 해당 토큰을 지속하려면 true로 설정합니다.
true
dbType의 값에 따라 OAuth 2.0 액세스 토큰(승인 부여)이 다른 위치에 저장됩니다. 다음 표에는 승인 부여가 저장된 데이터베이스의 위치에 대한 정보가 나와 있습니다.
dbType
승인 부여가 저장된 데이터베이스의 위치
postgres
ThingWorx PostgreSQL 데이터베이스의 oauth_client_token 테이블
mssql
ThingWorx MS SQL 데이터베이스의 oauth_client_token 테이블
다음 표에서는 sso-settings.json 파일에 있는 KeyManagerSettings 섹션의 서로 다른 매개 변수와 기본값을 설명합니다.
매개 변수
설명
값
keyStoreFilePath
키 저장소의 절대 파일 경로 위치를 지정합니다. 환경에 따라 키 저장소 파일이 저장된 디렉터리를 사용하도록 경로를 수정합니다.
* 
키 저장소 키에 대해 sso-settings.json 파일이 저장된 위치와 다른 스토리지 위치를 사용하는 것이 좋습니다. 따라서 이러한 파일에 더 세분화된 파일 시스템 액세스 제어를 적용할 수 있습니다. ThingWorx에 대한 일반 설정은 키 저장소 키 및 sso-settings.json 파일과 다른 위치에 저장해야 합니다.
Windows의 경우: <drive>:\\ThingworxPlatform\\ssoSecurityConfig\\sso-keystore.jks
여기서 <drive>에는 ThingWorx를 설치한 드라이브를 지정합니다.
Linux의 경우: <전체 경로>/ThingworxPlatform/ssoSecurityConfig/sso-keystore.jks
keyStoreStorePass
키 저장소 암호를 지정합니다.
—
keyStoreKey
기본 키를 지정합니다.
—
keyStoreKeyPass
개인 키에 액세스하는 데 사용되는 암호를 지정합니다.
—
다음 표에서는 sso-settings.json 파일에 있는 AuthorizationServersSettings 섹션의 서로 다른 매개 변수와 기본값을 설명합니다.
* 
AuthorizationServersSettings 설정에는 둘 이상의 인증 서버에 대한 정보가 포함될 수 있습니다. 각 서버는 sso-settings.json 파일에서 고유한 식별자로 식별됩니다.
매개 변수
설명
값
<AuthorizationServerId1>.clientId
인증 서버에서 액세스 토큰을 가져올 때 사용할 클라이언트 식별자를 지정합니다.
* 
AuthorizationServerId1 변수에 대해 제공할 값을 선택합니다. AuthorizationServerId1 변수의 이 값은 통합 커넥터 또는 미디어 엔티티에 대한 연결 설정을 구성하는 데 사용됩니다. 커넥터 설정을 구성하는 관리자 또는 개발자가 ssoSecurityConfig 디렉터리에 대한 액세스 권한을 가지고 있지 않는 경우 이 정보를 관리자 또는 개발자에게 제공해야 합니다.
—
<AuthorizationServerId1>.clientSecret
인증 서버에서 인증하는 데 사용되는 클라이언트 자격 증명을 지정합니다.
네트워크의 전체 도메인 이름 서버 URL로 설정합니다.
—
<AuthorizationServerId1>.authorizeUri
액세스 토큰을 승인하기 위해 사용자를 리디렉션할 URI를 지정합니다.
• PingFederate를 CAS로 사용:
https://<PingFederate-host-name>:<PingFederate-Port-Number>/as/authorization.oauth2
* 
PingFederate 설치와 함께 제공되는 PingFederate 런타임 포트를 사용하십시오.
• Microsoft Entra ID를 CAS로 사용: Microsoft Entra ID 권한 부여 설명서에서 ThingWorx 구성 파일 업데이트를 참조하십시오.
• Azure FS를 CAS로 사용: AD FS 권한 부여 설명서에서 ThingWorx 구성 파일 업데이트를 참조하십시오.
<AuthorizationServerId1>.tokenUri
OAuth2 액세스 토큰을 얻기 위해 사용할 URI를 지정합니다.
네트워크의 전체 도메인 이름 서버 URL로 설정합니다.
https://<PingFederate-host-name>:<PingFederate-Port-Number>/as/token.oauth2
* 
PingFederate 설치와 함께 제공되는 PingFederate 런타임 포트를 사용하십시오.
<AuthorizationServerId1>.clientAuthScheme
클라이언트를 인증하기 위해 사용할 스키마를 지정합니다. 허용된 값은 다음과 같습니다.
• 형태
• 헤더
• 질의
• 없음
form
<AuthorizationServerId1>.mandatoryScopes
Microsoft Entra ID 및 ADFS 이외의 CAS의 경우 선택 사항입니다. 이 매개 변수가 정의되면 요청된 모든 accessToken에 이 범위가 자동으로 추가됩니다.
* 
범위가 둘 이상인 경우 공백을 구분 기호로 사용합니다.
Microsoft Entra ID를 CAS로 사용하는 경우 필수입니다. 필수 값은 "offline_access"입니다.
ADFS의 경우 필수: 이는 ADFS 서버의 범위 목록에 정의되지 않은 값일 수 있습니다.
다음 표에서는 sso-settings.json 파일의 OIDCSettings 섹션에 있는 다양한 매개 변수와 기본값에 대해 설명합니다. 이 섹션은 인증 유형이 OIDC인 경우에만 필요합니다.
매개 변수
설명
값
openIdConfigurationUri
필수
이는 OpenID 서버 메타데이터의 URI입니다.
일반적으로 잘 알려진 URL에 게시됩니다.
clientId
인증 서버에서 액세스 토큰을 가져올 때 사용할 클라이언트 식별자를 지정합니다.
clientSecret
인증 서버에서 인증하는 데 사용되는 클라이언트 자격 증명을 지정합니다.
additionalScopes
선택 사항
OIDC 승인에 대한 추가 범위가 포함된 쉼표로 구분된 문자열입니다.
assertionUserNameAttributeName
ThingWorx 사용자가 로그인할 때 해당 사용자 이름을 저장하는 값을 전달하는 OpenID 클레임을 지정합니다. ID 공급자에서 이 속성의 값이 ThingWorx 사용자 이름에 대해 사용할 사용자 이름 값과 정렬되는지 확인합니다.
Azure AD B2C의 경우 - 이 속성의 값이 모든 ID 공급자 간에 고유한지 확인합니다.
accessTokenClaimsValidation
선택 사항
액세스 토큰 클레임 존재 및 클레임 값 유효성 검사를 지정합니다.
입력은 각 속성이 필수 클레임 이름이고 값이 필수 클레임 값인 간단한 JSON 문자열입니다. 값이 제공되지 않은 경우(빈 문자열) - 클레임 이름 존재만 유효성이 검사됩니다.
useAccessTokenClaims
선택 사항
사용자 확장 매핑에 대한 액세스 토큰 클레임을 검색할지 여부를 지정합니다.
다음과 같은 경우에만 이 속성을 true로 설정합니다.
• 액세스 토큰에는 openid 토큰에 포함되지 않고 사용자 확장에 필요한 클레임이 포함되어 있습니다.
• Azure AD B2C의 경우 - AzureSettings.apiEndPoint를 사용하여 사용자 그룹 정보를 검색하려는 경우입니다.
true/false
authorizeUriAdditionalParameters
선택 사항
OIDC 인증 추가 매개 변수입니다.
다음 표에서는 sso-settings.json 파일의 AzureSettings 섹션에 있는 다양한 매개 변수와 기본값에 대해 설명합니다. 이 섹션은 OIDC 구성이 포함된 Azure Entra ID에만 필요합니다.
매개 변수
설명
값
apiEndPoint
선택 사항
Azure 그래프 끝점
그룹 정보 검색에만 필요합니다(openid/액세스 토큰에 그룹 클레임이 포함되지 않은 경우).
* 
이 옵션을 사용하는 경우 OIDCSettings.useAccessTokenClaims를 true로 설정해야 합니다.
도움이 되셨나요?