Gmail S/MIME API는 Google Workspace 도메인의 사용자를 위해 S/MIME 이메일 인증서를 관리하는 프로그래매틱 액세스를 제공합니다.
인증서가 작동하려면 관리자가 도메인에 S/MIME를 사용 설정해야 합니다.
S/MIME 표준은 MIME 데이터의 공개 키 암호화 및 서명에 관한 사양을 제공합니다. 사용자 계정에서 S/MIME 인증서를 구성하면 Gmail에서 다음과 같은 방식으로 인증서를 사용합니다.
- Gmail은 사용자의 인증서와 비공개 키를 사용하여 발신 메일에 서명합니다.
- Gmail은 사용자의 비공개 키를 사용하여 수신 메일을 복호화합니다.
- Gmail은 수신자의 인증서와 공개 키를 사용하여 발신 메일을 암호화합니다.
- Gmail은 발신자의 인증서와 공개 키를 사용하여 수신 메일을 확인합니다.
개별 S/MIME 인증서를 생성하고 API를 사용하여 업로드합니다. 각 S/MIME 인증서는 사용자 이메일 계정의 특정 별칭에 관한 것입니다. 별칭에는 기본 이메일 주소와 맞춤 '다른 주소에서 보내기' 주소가 포함됩니다. 각 별칭에 대해 하나의 S/MIME 인증서가 기본값으로 표시됩니다.
API 액세스 승인
API 액세스를 승인하는 방법에는 두 가지가 있습니다.
- 도메인 전체 권한 위임과 함께 서비스 계정을 사용할 수 있습니다. 이러한 용어에 대한 설명은 인증 및 승인 개요 용어를 참고하세요. 이 옵션을 사용 설정하는 방법에 관한 자세한 내용은 도메인 전체 권한 위임을 통해 서비스 계정 만들기를 참고하세요.
- Oauth2 액세스 토큰을 얻기 위해 최종 사용자 동의가 필요한 표준 OAuth2 흐름을 사용할 수 있습니다. 자세한 내용은 인증 및 승인 개요를 참고하세요. 이 옵션을 사용하려면 도메인 관리자가 도메인 제어 패널에서 'S/MIME API 최종 사용자 액세스 사용 설정됨' 체크박스를 사용 설정해야 합니다.
ACL 범위
이 API는 Gmail sendAs 메서드와 동일한 ACL 범위를 사용합니다.
- gmail.settings.basic
- 기본 SendAs S/MIME를 업데이트하는 데 이 범위가 필요합니다.
- gmail.settings.sharing
- 이 범위는 S/MIME 에서 맞춤을 업데이트하는 데 필요합니다.
API 사용
users.settings.sendAs.smimeInfo 리소스는 S/MIME 인증서를 관리하는 데 사용하는 메서드를 제공합니다. 각 인증서는 사용자의 하나의 발신자 대리자 별칭과 연결됩니다.
S/MIME 키 업로드
smimeInfo.insert() 메서드를 사용하여 사용자의 별칭에 관한 새 S/MIME 키를 업로드합니다. 다음 매개변수를 사용하여 대상 별칭을 식별합니다.
- userId
- 사용자의 이메일 주소입니다. 특수 값
me
를 사용하여 현재 인증된 사용자를 나타낼 수 있습니다. - sendAsEmail
- 키를 업로드할 별칭입니다. 이 별칭을 사용하여 전송된 메일의 '보낸사람:' 헤더에 표시되는 이메일 주소입니다.
S/MIME 인증서와 비공개 키는 pkcs12
필드에 해당 형식으로 있어야 합니다. 요청에 다른 필드는 설정하면 안 됩니다. PKCS12 필드에는 사용자 S/MIME 키와 서명 인증서 체인이 모두 포함되어야 합니다. API는 이 필드를 수락하기 전에 표준 유효성 검사를 실행하여 다음을 확인합니다.
- 제목이 지정된 이메일 주소와 일치합니다.
- 만료일이 유효합니다.
- 발급 인증 기관 (CA)이 신뢰할 수 있는 목록에 있습니다.
- 인증서가 Gmail의 기술적 제약 조건과 일치합니다.
키가 암호화된 경우 비밀번호는 encryptedKeyPassword
필드에 있어야 합니다. insert() 호출이 성공하면 향후 키를 참조하는 데 사용할 수 있는 smimeInfo의 ID가 반환됩니다.
사용자의 S/MIME 키 나열
smimeInfo.list() 메서드를 사용하여 지정된 사용자의 지정된 별칭에 대한 S/MIME 키 목록을 반환합니다. 다음 매개변수를 사용하여 대상 별칭을 식별합니다.
- userId
- 사용자의 이메일 주소입니다. 특수 값
me
를 사용하여 현재 인증된 사용자를 나타낼 수 있습니다. - sendAsEmail
- 키를 나열할 별칭입니다. 이 별칭을 사용하여 전송된 메일의 '보낸사람:' 헤더에 표시되는 이메일 주소입니다.
별칭의 S/MIME 키 검색
smimeInfo.get() 메서드를 사용하여 사용자의 특정 발신자 별칭에 대한 특정 S/MIME 키를 반환합니다. 다음 매개변수를 사용하여 대상 별칭을 식별합니다.
- userId
- 사용자의 이메일 주소입니다. 특수 값
me
를 사용하여 현재 인증된 사용자를 나타낼 수 있습니다. - sendAsEmail
- 키를 검색할 별칭입니다. 이 별칭을 사용하여 전송된 메일의 '보낸사람:' 헤더에 표시되는 이메일 주소입니다.
S/MIME 키 삭제
smimeInfo.delete() 메서드를 사용하여 별칭에서 지정된 S/MIME 키를 삭제합니다. 다음 매개변수를 사용하여 대상 별칭을 식별합니다.
- userId
- 사용자의 이메일 주소입니다. 특수 값
me
를 사용하여 현재 인증된 사용자를 나타낼 수 있습니다. - sendAsEmail
- 키를 검색할 별칭입니다. 이 별칭을 사용하여 전송된 메일의 '보낸사람:' 헤더에 표시되는 이메일 주소입니다.
- id
- SmimeInfo의 변경 불가능한 ID입니다.
별칭의 기본 S/MIME 키 설정
smimeInfo.setDefault() 메서드를 사용하여 지정된 S/MIME 키를 지정된 별칭의 기본값으로 표시합니다. 다음 매개변수를 사용하여 대상 별칭을 식별합니다.
- userId
- 사용자의 이메일 주소입니다. 특수 값
me
를 사용하여 현재 인증된 사용자를 나타낼 수 있습니다. - sendAsEmail
- 키를 검색할 별칭입니다. 이 별칭을 사용하여 전송된 메일의 '보낸사람:' 헤더에 표시되는 이메일 주소입니다.
- id
- SmimeInfo의 변경 불가능한 ID입니다.
샘플 코드
다음 코드 샘플은 API를 사용하여 여러 사용자가 있는 조직의 S/MIME 인증서를 관리하는 방법을 보여줍니다.
S/MIME 인증서의 SmimeInfo 리소스 만들기
다음 코드 샘플은 파일에서 인증서를 읽고 base64url 문자열로 인코딩한 후 smimeInfo
리소스의 pkcs12
필드에 할당하는 방법을 보여줍니다.
자바
Python
S/MIME 인증서 업로드
인증서를 업로드하려면 smimeInfo.insert
를 호출하고 요청 본문에 smimeInfo
리소스를 제공합니다.
자바
Python
여러 사용자의 인증서를 관리하는 예
조직의 여러 사용자의 인증서를 한 번에 관리하려는 경우가 있습니다. 다음 예는 한 번의 일괄 호출로 여러 사용자의 인증서를 관리하는 방법을 보여줍니다.
CSV 파일에서 인증서 삽입
사용자 ID와 각 사용자 인증서의 경로가 나열된 CSV 파일이 있다고 가정해 보겠습니다.
$ cat certificates.csv
user1@example.com,/path/to/user1_cert.p12,cert_password_1
user2@example.com,/path/to/user2_cert.p12,cert_password_2
user3@example.com,/path/to/user3_cert.p12,cert_password_3
자바
앞의 createSmimeInfo
및 insertSmimeInfo
호출을 사용하여 CSV 파일에 지정된 대로 인증서를 업로드할 수 있습니다.
Python
앞의 create_smime_info
및 insert_smime_info
호출을 사용하여 CSV 파일에 지정된 대로 인증서를 업로드할 수 있습니다.
인증서 관리
이 예에서는 smimeInfo
API의 여러 호출을 결합하여 조직의 인증서를 관리하는 방법을 보여줍니다. 사용자의 인증서를 나열하고 기본 인증서가 만료되었거나 설정되지 않은 경우 지정된 파일에서 찾은 인증서를 업로드합니다. 그런 다음 만료일이 가장 먼 인증서를 기본값으로 설정합니다.
그런 다음 이전 예와 같이 CSV 파일을 처리하는 함수에서 호출됩니다.